@warp-org/container

Status

• Lifecycle: active
• Maintainer/Owner: TBD
• Last reviewed: TBD

Purpose and Context

Lightweight dependency container package used across multiple org repositories to provide deterministic service resolution with minimal DI boilerplate.

Architecture

Primary implementation file: container.ts

Core concepts:

• Injectable<T> token can be class constructor or factory function
• singleton instance registry (instances)
• provider registry for transient/fresh resolution (providers)
• memoization cache (memos)

Resolution flow:

1. app(service) delegates to Container.resolve.
2. Missing services auto-register using constructor/factory.
3. fresh=true returns new provider instance without replacing singleton cache.

Setup

Prerequisites

• Node.js (LTS)
• npm

Local development

npm install
npm run build

Package publishing workflow

npm run build
npm publish --access public
# or
npm run publish:public

Environment Variables

No environment variables are required by this library package.

Variable	Required	Default	Example	Secret	Used by	Notes
None	N/A	N/A	N/A	N/A	N/A	Runtime behavior is config-free

Operations Runbook

Build and verify

npm run build

Common troubleshooting

• Unexpected stale singleton: use Container.unregister(Service) and resolve again.
• Stale memoized result: call Container.refresh(fn) before reuse.

API/Integration Contract

app(service, fresh?)

Resolve service from container.

const client = app(ApiClient);
const transient = app(ApiClient, true);

Container.register(token, factory?)

Bind abstraction to implementation.

Container.register(DatabaseClient, () => new PostgresClient());

Container.resolve(token, fresh?)

Low-level equivalent of app.

Container.memo(fn)

Memoize pure function by argument signature.

const fib = Container.memo((n: number): number => {
  return n < 2 ? n : fib(n - 1) + fib(n - 2);
});

Security Notes

• Avoid storing secrets in singleton services directly; inject secret providers instead.
• Memoization stores return values in-memory; do not memoize sensitive material unless required.

Development Workflow

1. Branch from main.
2. Implement API-compatible changes in container.ts.
3. Build and verify package output:

npm run build

4. Update README usage examples for any API changes.
5. Publish only from reviewed tags/releases.

Maintenance Guide

• Preserve backwards compatibility for app, register, resolve, and memo.
• Keep TypeScript output and declaration files stable.
• Document behavioral changes with migration notes in README and release notes.