@rhombus-std/di.core 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Butler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,367 @@
+# @rhombus-std/di.core
+
+> **Published abstractions package.** `@rhombus-std/di.core` is the abstractions
+> substrate `@rhombus-std/di` depends on and re-exports — mirroring the reference
+> DI split where the abstractions package ships the concrete registration
+> collection and the runtime package supplies the provider. `@rhombus-std/di`
+> keeps it **external** (not inlined) so there is one shared `@rhombus-std/di.core`
+> module identity: the `ServiceManifestClass` `di` patches `build()` onto, and the
+> class cross-package augmentations patch, are the same object. An app installs
+> `@rhombus-std/di` (and `@rhombus-std/di.transformer` for the compile-time plugin)
+> and reaches the authoring surface through di's re-exports; a **library** author
+> depends on `@rhombus-std/di.core` directly to author registrations without the
+> resolution engine.
+
+The substrate for `ioc`. It ships the immutable dependency-signature data format
+(`DepSlot` and its variants), the open-generic token grammar with its
+guard/constructor helpers (`union`, `typeArg`), the registration ABI, and — the
+runtime footprint — the concrete registration builder `ServiceManifestClass`
+(`add` / `addFactory` / `addValue`; `build()` is a `@rhombus-std/di` extension)
+plus the registration-time errors (`DiError`, `OpenTokenRegistrationError`). The
+resolution engine (`ServiceProviderClass`) and resolution-time errors live in
+[`@rhombus-std/di`](../di/README.md). There is no metadata store here, or anywhere
+else: a constructor/factory's dependency signature rides on the registration
+itself.
+
+---
+
+## `Token`
+
+A plain `string`. The DI key identifying an interface. No branding, no literal types. Generated by the transformer at build time; passed explicitly in plugin-less usage.
+
+```ts
+export type Token = string;
+```
+
+---
+
+## `FactoryRef`
+
+Marks a constructor parameter to be injected as a factory rather than a resolved instance.
+
+```ts
+export interface FactoryRef {
+  readonly type: Token;
+  readonly params?: readonly Token[];
+}
+```
+
+`type` is the token of the produced type T. `params` is the complete, authored-order list of caller-supplied parameter tokens — passing it pins the factory's shape so it no longer drifts as registration state changes. Omit `params` to get a strict zero-arg `() => T` where every slot must resolve from the container.
+
+---
+
+## `RESOLVER_TOKEN` / the provider as a resolvable type
+
+The provider is an intrinsically resolvable type — no dedicated slot kind. A parameter typed `Resolver` derives the ordinary token `RESOLVER_TOKEN`, and the engine resolves it to the nearest open scope's provider VIEW rather than a registration, so "I want the provider" is plain DI. A plugin-less author hand-feeds the exported constant in a signature:
+
+```ts
+import { RESOLVER_TOKEN } from "@rhombus-std/di.core";
+
+services.addFactory("app/IReport", (sp) => buildReport(sp), [[RESOLVER_TOKEN]]);
+```
+
+`isProviderToken(token)` is the runtime predicate the engine uses. (This retires the former `{ scope: true }` `ScopeRef` slot marker — the provider token subsumes it.)
+
+---
+
+## `Union`
+
+A slot that tries each member in declaration order and resolves to the first one that is registered.
+
+```ts
+export interface Union {
+  readonly union: readonly DepSlot[];
+}
+```
+
+Members are tried in array order (first = highest precedence). If no member is resolvable, the container throws. Each member is itself a `DepSlot`, so nesting is allowed.
+
+### `union(...slots)`
+
+Ergonomic constructor:
+
+```ts
+export function union(...slots: DepSlot[]): Union;
+```
+
+```ts
+services.add("pkg:IHandler", Handler, [[
+  union("pkg:IRedis", "pkg:IMemoryCache"),
+  "pkg:ILogger",
+]]);
+```
+
+---
+
+## `TypeArgRef`
+
+Marks a constructor parameter to be injected with the **token string** of one of an open registration's type arguments — the `typeof(T)` analog for open-generic templates.
+
+```ts
+export interface TypeArgRef {
+  readonly typeArg: number;
+}
+```
+
+`typeArg` is the 1-based hole number (`{ typeArg: 1 }` names the argument bound to `$1`). It only ever appears raw inside an **open** registration's carried signature. At close time, substitution replaces it with a `LiteralRef` carrying the substituted argument's token string — a raw `TypeArgRef` reaching resolution is a bug (unsatisfiable; fails loud rather than silently falling into the token branch). Authored via `Typeof<T>` (below) or, by hand, `typeArg(n)`.
+
+---
+
+## `Inject<T, K extends Token>`
+
+A phantom brand type. Pins the token for one constructor or factory parameter without changing the value type.
+
+```ts
+declare const TOK: unique symbol;
+export type Inject<T, K extends Token> = T & { readonly [TOK]?: K };
+```
+
+The brand is optional — a plain `T` is still assignable. Zero runtime cost.
+
+```ts
+// Pin a specific token for one arg; others derive normally
+class Handler {
+  constructor(
+    a: Inject<ICache, "pkg:redis-cache">,
+    b: ILogger,
+  ) {}
+}
+```
+
+Works in any type position the transformer reads: class ctor params, inline factory params, return types. Use it as the escape hatch for anonymous or purely structural types — types with no name that the transformer cannot otherwise tokenize — `Inject<{ n: number }, "my:opts">`. Named types (interfaces, classes, primitive keywords) derive a token on their own and do not need `Inject`.
+
+Re-exported by `@rhombus-std/di.transformer`.
+
+---
+
+## `Hole<N, C>` and `$<N>`
+
+Compile-time skolems — placeholders standing in for the `N`th type argument of an open-generic template (1-based, mirrors the `Inject` brand pattern above).
+
+```ts
+declare const HOLE: unique symbol;
+export type Hole<N extends number, C = unknown> = C & { readonly [HOLE]?: N };
+
+export type $<N extends number> = Hole<N>;
+```
+
+`$<N>` is unbounded sugar for the common unconstrained case (`$<1>` = `Hole<1>`, `$<2>` = `Hole<2>`, … no upper bound). Write `Hole<N, C>` directly when the implementation's type parameter carries a constraint the skolem needs to satisfy — `Hole<1, Entity>` **is** an `Entity` (the brand property is optional, so the intersection stays assignable to `C`), letting a constrained impl like `class SqlRepository<T extends Entity>` accept a hole as its type argument:
+
+```ts
+services.add<IRepository<$<1>>>(SqlRepository<Hole<1, Entity>>);
+```
+
+Zero runtime footprint — like `Inject`, these are pure compile-time brands read structurally by `@rhombus-std/di.transformer`. See [`@rhombus-std/di.transformer`](../di.transformer/README.md#open-generics) for how they drive token derivation and instantiation expressions.
+
+---
+
+## `Typeof<T>`
+
+A phantom brand marking a constructor parameter that receives the **token string** of type argument `T` — the `typeof(T)` analog (hence the name).
+
+```ts
+declare const ARG: unique symbol;
+export type Typeof<T> = Token & { readonly [ARG]?: T };
+```
+
+`Typeof<T>` is type-driven — the transformer infers the hole from `T`; its manual counterpart `typeArg(n)` is positional. The value type stays `Token` (a plain string) — the brand property is optional, so any string is assignable. When `T` resolves to a `Hole`, the transformer emits an open `TypeArgRef` slot (`{ typeArg: N }`) that substitution closes per registration; when `T` is concrete (a closed registration via an instantiation expression), it emits the derived token directly as a `LiteralRef` value slot — no substitution step needed.
+
+```ts
+class SqlRepository<T> implements IRepository<T> {
+  constructor(
+    private db: IDbConnection,
+    private entityToken: Typeof<T>,
+  ) {}
+}
+
+services.add<IRepository<$<1>>>(SqlRepository<$<1>>);
+
+const userRepo = scope.resolve<IRepository<User>>();
+// userRepo.entityToken === "pkg:User"
+```
+
+---
+
+## `DepSlot`
+
+One positional slot in a constructor signature:
+
+```ts
+export type DepSlot =
+  | Token
+  | FactoryRef
+  | Union
+  | LiteralRef
+  | TypeArgRef;
+```
+
+- `Token` — a container-resolved dep (registered) or a caller-supplied param (unregistered); the live registration map determines which at resolve time. The intrinsic provider token (`RESOLVER_TOKEN`) resolves to the live provider view.
+- `FactoryRef` — a factory-injected parameter.
+- `Union` — member-level alternatives; first resolvable wins.
+- `LiteralRef` — a singular literal or nullish-singleton value, injected directly, no container lookup, always satisfiable.
+- `TypeArgRef` — the token string of an open registration's `N`th type argument; substituted to a `LiteralRef` at close time (see `TypeArgRef` above).
+
+An unregistered token slot is caller-supplied by definition; a `TypeArgRef` slot is only ever satisfiable through substitution, never directly.
+
+---
+
+## `DepRecord`
+
+The shape of a registration's carried dependency metadata — not stored anywhere globally; it's the type of the array a registration passes as its own signature(s).
+
+```ts
+export interface DepRecord {
+  readonly signatures: readonly (readonly DepSlot[])[];
+}
+```
+
+`signatures` holds one or many signature arrays, supporting constructor overloads without an ABI break — the engine picks the first satisfiable one, scanned longest to shortest (see [`@rhombus-std/di`](../di/README.md#greedy-overload-selection)).
+
+---
+
+## Authoring dependency signatures by hand
+
+There is no global metadata store and no decorator. A signature rides directly
+on the registration, passed as the optional **third argument** to
+`@rhombus-std/di`'s `add` / `addFactory`:
+
+```ts
+import { ServiceManifest } from "@rhombus-std/di";
+
+const services = new ServiceManifest();
+
+services.add("pkg:IHandler", Handler, [
+  ["pkg:ILogger", "pkg:IDb"], // overload 0 — one signature per constructor overload
+]);
+```
+
+`@rhombus-std/di.transformer` emits this array inline for every registration it can
+statically extract a signature from, rewriting the type-driven `add<IFoo>(Foo)`
+to `add("pkg:IFoo", Foo, [[...]])` — there is no separate prelude call and
+nothing hoisted; the signature travels with the registration itself. Hand
+authoring (no transformer) means writing the array yourself, using the slot
+builders above (`union`, `typeArg`) plus plain token strings (including
+`RESOLVER_TOKEN` for the provider), `FactoryRef` / `LiteralRef` object literals,
+and the token-grammar helpers below for open generics. Omitting the third
+argument leaves the registration
+signature-less — fine for a zero-arg constructor, but resolution throws
+`MissingMetadataError` for any constructor with parameters.
+
+Because the array is keyed on the **registration record**, not on the
+constructor function, one JS class can back any number of independent
+registrations with different signatures — the mechanism open-generics
+registrations depend on, where the same erased class serves every closing of a
+template. See [Open-generic token grammar](#open-generic-token-grammar) below
+and [`@rhombus-std/di`](../di/README.md#open-generics).
+
+---
+
+## Open-generic token grammar
+
+Closing a generic is token algebra, not runtime type machinery — TypeScript generics are erased, so there is exactly one JS class per generic implementation. `@rhombus-std/di.transformer` renders the grammar below at build time; these functions are how `@rhombus-std/di`'s resolve-time fallback (and any hand-written manual registration) works with it directly.
+
+**Closed-generic grammar (canonical, recursive):** `base<arg1,arg2>` — no whitespace around `<` `>` `,`. Each arg is itself a token, so nesting recurses (`pkg:IFoo<pkg:IBar<./src/Baz>>`). A **hole** is an arg that is exactly `$N` (decimal, `N ≥ 1`); a token containing a hole at any depth is an _open template_. Literal-type args keep their interior spaces/quotes (`"a" | "b"`) — the parser is quote-aware, so commas and angle brackets inside double quotes never count as separators.
+
+### `closeToken(base, ...args)`
+
+```ts
+export function closeToken(base: Token, ...args: Token[]): Token;
+```
+
+Renders the canonical form. With no args, returns `base` unchanged.
+
+```ts
+closeToken("pkg:IRepository", "pkg:User"); // "pkg:IRepository<pkg:User>"
+closeToken("pkg:IMap", "string", "$1"); // "pkg:IMap<string,$1>"
+```
+
+### `parseToken(token)`
+
+```ts
+export interface ParsedToken {
+  readonly base: Token;
+  readonly args: readonly Token[];
+}
+export function parseToken(token: Token): ParsedToken | undefined;
+```
+
+Splits a closed-generic token into its base and top-level args. Returns `undefined` for non-generic tokens (no top-level `<`) and for malformed input (unbalanced brackets, empty arg, trailing text after the closing `>`, unterminated quote) — callers fall through to their normal exact-match / unregistered-token handling either way.
+
+### `isOpenToken(token)`
+
+```ts
+export function isOpenToken(token: Token): boolean;
+```
+
+True when `token` contains a hole (`$N`) at any depth — grammar-aware, so a `$N` inside a quoted literal arg is not a hole.
+
+### `substituteToken(template, args)`
+
+```ts
+export function substituteToken(template: Token, args: readonly Token[]): Token;
+```
+
+Grammar-aware, recursive substitution — NOT a naive string replace. A node that is exactly `$N` is replaced by `args[N - 1]` (which may itself be a closed-generic token); everything else recurses through the parsed structure. Throws `RangeError` if the template references a hole beyond the supplied args.
+
+```ts
+substituteToken("pkg:IRepository<$1>", ["pkg:User"]);
+// → "pkg:IRepository<pkg:User>"
+```
+
+### `substituteSignatures(signatures, args)`
+
+```ts
+export function substituteSignatures(
+  signatures: readonly (readonly DepSlot[])[],
+  args: readonly Token[],
+): readonly (readonly DepSlot[])[];
+```
+
+Substitutes `args` through every slot of every signature — the whole-record counterpart to `substituteToken`, used to close an open registration's carried dep signatures at resolve time. Per slot: a string token → `substituteToken`; a `FactoryRef` → its `type` and each `params` token substituted; a `Union` → members substituted recursively; a `TypeArgRef` → a `LiteralRef` carrying `args[typeArg - 1]`; a `LiteralRef` passes through unchanged.
+
+### `typeArg(n)` and `isTypeArgRef`
+
+```ts
+export function typeArg(n: number): TypeArgRef;
+export function isTypeArgRef(slot: DepSlot): slot is TypeArgRef;
+```
+
+`typeArg(n)` is the manual-authoring counterpart to `Typeof<T>` — build a `{ typeArg: n }` slot by hand when writing an open registration's signature array directly (no transformer). `isTypeArgRef` is the type guard, alongside `isFactoryRef` / `isUnionSlot` / `isLiteralRef`.
+
+---
+
+## Versioning
+
+`@rhombus-std/di.core` is versioned independently via release-please (semver). The dep-metadata format (`DepRecord`) is kept backward-compatible across `core` semver minors; a breaking change to the wire format would require a coordinated update across all packages.
+
+---
+
+## Exports summary
+
+| Export                 | Kind       | Description                                                                                                        |
+| ---------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| `Token`                | Type alias | `string` — the DI key type.                                                                                        |
+| `FactoryRef`           | Interface  | `{ type: Token; params?: readonly Token[] }` — factory-injected parameter slot.                                    |
+| `RESOLVER_TOKEN`       | Const      | The intrinsic provider token — resolves to the live provider view (a `Resolver`-typed param derives it).           |
+| `isProviderToken`      | Function   | `(token) => boolean` — true for the intrinsic provider token(s).                                                   |
+| `Union`                | Interface  | `{ union: readonly DepSlot[] }` — member-level alternatives.                                                       |
+| `union`                | Function   | Construct a `Union` slot from variadic `DepSlot` args.                                                             |
+| `LiteralRef`           | Interface  | `{ value }` — a singular literal / nullish-singleton slot, injected directly.                                      |
+| `TypeArgRef`           | Interface  | `{ typeArg: number }` — the token string of an open registration's `N`th type argument.                            |
+| `Inject`               | Type alias | Phantom brand — pins a token for one param without changing the value type.                                        |
+| `Hole`                 | Type alias | `Hole<N, C>` — compile-time skolem for the `N`th type argument of an open template, optionally constrained to `C`. |
+| `$`                    | Type alias | `$<N>` — unbounded unconstrained sugar for `Hole<N>`.                                                              |
+| `Typeof`               | Type alias | Phantom brand — a ctor param receiving the token string of type argument `T` (`typeof(T)` analog).                 |
+| `DepSlot`              | Type alias | `Token \| FactoryRef \| Union \| LiteralRef \| TypeArgRef` — one positional slot in a signature.                   |
+| `DepTarget`            | Type alias | `Ctor \| Func<never[], unknown>` — a ctor or factory function a signature describes.                               |
+| `DepRecord`            | Interface  | `{ signatures }` — per-registration signature-array shape.                                                         |
+| `isFactoryRef`         | Function   | Type guard for `FactoryRef` slots.                                                                                 |
+| `isUnionSlot`          | Function   | Type guard for `Union` slots.                                                                                      |
+| `isLiteralRef`         | Function   | Type guard for `LiteralRef` slots.                                                                                 |
+| `closeToken`           | Function   | Render the canonical closed-generic token `base<a,b>`.                                                             |
+| `parseToken`           | Function   | Parse a closed-generic token into `{ base, args }`, or `undefined`.                                                |
+| `isOpenToken`          | Function   | True when a token contains a hole (`$N`) at any depth.                                                             |
+| `substituteToken`      | Function   | Grammar-aware substitution of holes in a token template.                                                           |
+| `substituteSignatures` | Function   | Substitute type args through every slot of every signature.                                                        |
+| `typeArg`              | Function   | Build a `TypeArgRef` slot (`{ typeArg: n }`) by hand.                                                              |
+| `isTypeArgRef`         | Function   | Type guard for `TypeArgRef` slots.                                                                                 |