Skip to content

Latest commit

 

History

History
127 lines (84 loc) · 2.77 KB

README.md

File metadata and controls

127 lines (84 loc) · 2.77 KB

@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
  1. Update README usage examples for any API changes.
  2. 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.