zodbridge 0.2.0

package/dist/context-B0f9mQWu.d.cts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+
+/**
+ * Resolver-graph context: dependency-aware, memoizing, cycle-guarded lazy field
+ * resolution. A faithful generalization of a `ContextResolver`-style engine.
+ *
+ * Invariants (do not "optimize" away):
+ *  (a) The promise for a field is stored in `cache` BEFORE the first await, so
+ *      concurrent `Promise.all` over a shared dep fires its resolver once.
+ *  (b) The touched-check (`cache` ∪ `inProgress`) serializes a field's re-entry,
+ *      breaking cycles.
+ *  (c) A resolver that THROWS rejects and evicts its cache entry — errors are
+ *      never coerced to `undefined` and never cached. Only a RETURNED `undefined`
+ *      is cached as a terminal value.
+ *  (d) `fallback` retries the calling field by re-invoking its resolver FUNCTION
+ *      directly, bypassing the step-1 cache short-circuit, so a momentarily
+ *      `undefined` field can still resolve once a dependency becomes available.
+ *  (e) The calling field for `fallback` is bound per resolver invocation (a
+ *      field-bound context), NOT read from shared instance state — so two
+ *      fallback-using resolvers running concurrently never contaminate each
+ *      other's retry target.
+ */
+
+/** A resolver function for one field; may use the context to derive its value. */
+type ResolverFn<Fields, TAdapter, K extends keyof Fields> = (ctx: ResolverContext<Fields, TAdapter>) => Fields[K] | undefined | Promise<Fields[K] | undefined>;
+/** Registry of per-field resolvers (declarative; not class methods). */
+type ResolverRegistry<Fields, TAdapter> = {
+    [K in keyof Fields]?: ResolverFn<Fields, TAdapter, K>;
+};
+/**
+ * Per-field Zod schemas used to validate resolver outputs at runtime. Built by
+ * the schema-driven `createResolver` overload from `maps` + `fields`; a field
+ * with no entry here is not validated (e.g. hand-written-`Fields` callers).
+ */
+type ResolverSchemas<Fields> = Partial<Record<keyof Fields, z.ZodType>>;
+/** Construction config for a resolver graph. */
+interface ResolverConfig<Fields, TAdapter> {
+    adapter: TAdapter;
+    seed?: Partial<Fields>;
+    resolvers?: ResolverRegistry<Fields, TAdapter>;
+    /**
+     * Optional per-field schemas. When present for a field, its resolver's output
+     * is parsed (and unknown keys stripped) before caching; a parse failure
+     * rejects `resolve` and evicts the entry. Seed values are NOT validated.
+     */
+    schemas?: ResolverSchemas<Fields>;
+    /**
+     * Optional observer fired after a field's resolver settles successfully (post
+     * validation), for tracing/debugging. Never fired for seed/terminal values.
+     * Throwing here does not affect resolution (the hook is best-effort).
+     */
+    onResolve?: (field: keyof Fields, value: unknown) => void;
+}
+/** The context object handed to every resolver and returned to callers. */
+interface ResolverContext<Fields, TAdapter> {
+    readonly adapter: TAdapter;
+    /** Resolve one field: cache -> seed -> resolver -> `undefined`. Memoized. */
+    resolve<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+    /** Resolve several fields; returns only the requested keys. */
+    resolveMany<K extends keyof Fields>(...fields: K[]): Promise<Partial<Pick<Fields, K>>>;
+    /** Cache peek: the resolved value if present, else `undefined`. No I/O. */
+    get<K extends keyof Fields>(field: K): Fields[K] | undefined;
+    /** Pure nested peek into seed + cache for `field`. Never resolves, never I/O. */
+    path<K extends keyof Fields>(field: K, keyPath: string[]): unknown;
+    /** Resolve untouched `deps`, then retry the calling field's resolver fn. */
+    fallback(deps: Array<keyof Fields>): Promise<unknown>;
+    /**
+     * Forget a field's cached value (and any settled peek) so the next `resolve`
+     * re-runs its resolver. Use after a write to force a fresh fetch from the
+     * adapter. Seed values are also dropped for the field. Returns `this`.
+     */
+    invalidate(...fields: Array<keyof Fields>): ResolverContext<Fields, TAdapter>;
+    /** Invalidate then re-resolve `field` — a forced sync re-fetch from the adapter. */
+    refresh<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+}
+declare class GraphContext<Fields, TAdapter> implements ResolverContext<Fields, TAdapter> {
+    readonly adapter: TAdapter;
+    private readonly seed;
+    private readonly resolvers;
+    private readonly schemas;
+    private readonly onResolve?;
+    /** Durable promise-cache: every attempted field lives here. */
+    private readonly cache;
+    /** Synchronously-readable settled values, for `get`/`path` peeks. */
+    private readonly settled;
+    /** Fields with an in-flight resolver; transient cycle guard. */
+    private readonly inProgress;
+    /** Fields explicitly invalidated: prefer the resolver over seed on next resolve. */
+    private readonly invalidated;
+    constructor(config: ResolverConfig<Fields, TAdapter>);
+    /** Synchronous peek of seed first, then any settled resolved value. */
+    private peek;
+    get<K extends keyof Fields>(field: K): Fields[K] | undefined;
+    path<K extends keyof Fields>(field: K, keyPath: string[]): unknown;
+    /** Public entry: a fresh resolution chain with no ancestors. */
+    resolve<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+    /**
+     * Resolve `field` within a chain whose currently-resolving fields are
+     * `ancestors`. If `field` is itself an ancestor, this is a dependency cycle
+     * (mutual A<->B, longer A->B->C->A, or self x->x): return `undefined` so the
+     * caller (e.g. a `strategies` candidate) falls through to its next route,
+     * instead of awaiting its own still-pending promise (which would deadlock).
+     *
+     * The ancestor check runs BEFORE the `cache.has` short-circuit, so a CONCURRENT
+     * caller (a parallel `Promise.all` chain — `field` is in-flight but NOT its
+     * ancestor) still receives the shared pending promise and dedups normally.
+     */
+    private resolveWithin;
+    /**
+     * A context bound to `self` and the chain's `ancestors`: identical to the
+     * top-level context except `resolve`/`fallback` carry the chain so cycles
+     * break (see {@link resolveWithin}) and `fallback` retries the right field.
+     * Binding per invocation (not shared instance state) keeps concurrent
+     * resolutions from contaminating each other.
+     */
+    private boundContext;
+    invalidate(...fields: Array<keyof Fields>): ResolverContext<Fields, TAdapter>;
+    refresh<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+    /** Fire the best-effort `onResolve` observer; never let it break resolution. */
+    private emitResolved;
+    private runResolver;
+    /**
+     * Validate a resolver's output against its field schema (if any). A defined
+     * value is parsed (unknown keys stripped); a parse failure throws the ZodError,
+     * which the reject branch turns into an eviction. `undefined` is the forgiving
+     * absence terminal and is never validated.
+     */
+    private validate;
+    /** Resolve untouched `deps`, then retry `self`'s resolver if any produced a value. */
+    private fallbackFor;
+    /**
+     * Top-level `fallback` has no calling field, so there is nothing to retry.
+     * Resolvers always receive a field-bound context whose `fallback` does retry;
+     * this entry exists only to satisfy the public {@link ResolverContext} shape.
+     */
+    fallback(_deps: Array<keyof Fields>): Promise<unknown>;
+    resolveMany<K extends keyof Fields>(...fields: K[]): Promise<Partial<Pick<Fields, K>>>;
+}
+
+export { GraphContext as G, type ResolverContext as R, type ResolverRegistry as a, type ResolverConfig as b, type ResolverFn as c, type ResolverSchemas as d };

package/dist/context-B0f9mQWu.d.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+
+/**
+ * Resolver-graph context: dependency-aware, memoizing, cycle-guarded lazy field
+ * resolution. A faithful generalization of a `ContextResolver`-style engine.
+ *
+ * Invariants (do not "optimize" away):
+ *  (a) The promise for a field is stored in `cache` BEFORE the first await, so
+ *      concurrent `Promise.all` over a shared dep fires its resolver once.
+ *  (b) The touched-check (`cache` ∪ `inProgress`) serializes a field's re-entry,
+ *      breaking cycles.
+ *  (c) A resolver that THROWS rejects and evicts its cache entry — errors are
+ *      never coerced to `undefined` and never cached. Only a RETURNED `undefined`
+ *      is cached as a terminal value.
+ *  (d) `fallback` retries the calling field by re-invoking its resolver FUNCTION
+ *      directly, bypassing the step-1 cache short-circuit, so a momentarily
+ *      `undefined` field can still resolve once a dependency becomes available.
+ *  (e) The calling field for `fallback` is bound per resolver invocation (a
+ *      field-bound context), NOT read from shared instance state — so two
+ *      fallback-using resolvers running concurrently never contaminate each
+ *      other's retry target.
+ */
+
+/** A resolver function for one field; may use the context to derive its value. */
+type ResolverFn<Fields, TAdapter, K extends keyof Fields> = (ctx: ResolverContext<Fields, TAdapter>) => Fields[K] | undefined | Promise<Fields[K] | undefined>;
+/** Registry of per-field resolvers (declarative; not class methods). */
+type ResolverRegistry<Fields, TAdapter> = {
+    [K in keyof Fields]?: ResolverFn<Fields, TAdapter, K>;
+};
+/**
+ * Per-field Zod schemas used to validate resolver outputs at runtime. Built by
+ * the schema-driven `createResolver` overload from `maps` + `fields`; a field
+ * with no entry here is not validated (e.g. hand-written-`Fields` callers).
+ */
+type ResolverSchemas<Fields> = Partial<Record<keyof Fields, z.ZodType>>;
+/** Construction config for a resolver graph. */
+interface ResolverConfig<Fields, TAdapter> {
+    adapter: TAdapter;
+    seed?: Partial<Fields>;
+    resolvers?: ResolverRegistry<Fields, TAdapter>;
+    /**
+     * Optional per-field schemas. When present for a field, its resolver's output
+     * is parsed (and unknown keys stripped) before caching; a parse failure
+     * rejects `resolve` and evicts the entry. Seed values are NOT validated.
+     */
+    schemas?: ResolverSchemas<Fields>;
+    /**
+     * Optional observer fired after a field's resolver settles successfully (post
+     * validation), for tracing/debugging. Never fired for seed/terminal values.
+     * Throwing here does not affect resolution (the hook is best-effort).
+     */
+    onResolve?: (field: keyof Fields, value: unknown) => void;
+}
+/** The context object handed to every resolver and returned to callers. */
+interface ResolverContext<Fields, TAdapter> {
+    readonly adapter: TAdapter;
+    /** Resolve one field: cache -> seed -> resolver -> `undefined`. Memoized. */
+    resolve<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+    /** Resolve several fields; returns only the requested keys. */
+    resolveMany<K extends keyof Fields>(...fields: K[]): Promise<Partial<Pick<Fields, K>>>;
+    /** Cache peek: the resolved value if present, else `undefined`. No I/O. */
+    get<K extends keyof Fields>(field: K): Fields[K] | undefined;
+    /** Pure nested peek into seed + cache for `field`. Never resolves, never I/O. */
+    path<K extends keyof Fields>(field: K, keyPath: string[]): unknown;
+    /** Resolve untouched `deps`, then retry the calling field's resolver fn. */
+    fallback(deps: Array<keyof Fields>): Promise<unknown>;
+    /**
+     * Forget a field's cached value (and any settled peek) so the next `resolve`
+     * re-runs its resolver. Use after a write to force a fresh fetch from the
+     * adapter. Seed values are also dropped for the field. Returns `this`.
+     */
+    invalidate(...fields: Array<keyof Fields>): ResolverContext<Fields, TAdapter>;
+    /** Invalidate then re-resolve `field` — a forced sync re-fetch from the adapter. */
+    refresh<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+}
+declare class GraphContext<Fields, TAdapter> implements ResolverContext<Fields, TAdapter> {
+    readonly adapter: TAdapter;
+    private readonly seed;
+    private readonly resolvers;
+    private readonly schemas;
+    private readonly onResolve?;
+    /** Durable promise-cache: every attempted field lives here. */
+    private readonly cache;
+    /** Synchronously-readable settled values, for `get`/`path` peeks. */
+    private readonly settled;
+    /** Fields with an in-flight resolver; transient cycle guard. */
+    private readonly inProgress;
+    /** Fields explicitly invalidated: prefer the resolver over seed on next resolve. */
+    private readonly invalidated;
+    constructor(config: ResolverConfig<Fields, TAdapter>);
+    /** Synchronous peek of seed first, then any settled resolved value. */
+    private peek;
+    get<K extends keyof Fields>(field: K): Fields[K] | undefined;
+    path<K extends keyof Fields>(field: K, keyPath: string[]): unknown;
+    /** Public entry: a fresh resolution chain with no ancestors. */
+    resolve<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+    /**
+     * Resolve `field` within a chain whose currently-resolving fields are
+     * `ancestors`. If `field` is itself an ancestor, this is a dependency cycle
+     * (mutual A<->B, longer A->B->C->A, or self x->x): return `undefined` so the
+     * caller (e.g. a `strategies` candidate) falls through to its next route,
+     * instead of awaiting its own still-pending promise (which would deadlock).
+     *
+     * The ancestor check runs BEFORE the `cache.has` short-circuit, so a CONCURRENT
+     * caller (a parallel `Promise.all` chain — `field` is in-flight but NOT its
+     * ancestor) still receives the shared pending promise and dedups normally.
+     */
+    private resolveWithin;
+    /**
+     * A context bound to `self` and the chain's `ancestors`: identical to the
+     * top-level context except `resolve`/`fallback` carry the chain so cycles
+     * break (see {@link resolveWithin}) and `fallback` retries the right field.
+     * Binding per invocation (not shared instance state) keeps concurrent
+     * resolutions from contaminating each other.
+     */
+    private boundContext;
+    invalidate(...fields: Array<keyof Fields>): ResolverContext<Fields, TAdapter>;
+    refresh<K extends keyof Fields>(field: K): Promise<Fields[K] | undefined>;
+    /** Fire the best-effort `onResolve` observer; never let it break resolution. */
+    private emitResolved;
+    private runResolver;
+    /**
+     * Validate a resolver's output against its field schema (if any). A defined
+     * value is parsed (unknown keys stripped); a parse failure throws the ZodError,
+     * which the reject branch turns into an eviction. `undefined` is the forgiving
+     * absence terminal and is never validated.
+     */
+    private validate;
+    /** Resolve untouched `deps`, then retry `self`'s resolver if any produced a value. */
+    private fallbackFor;
+    /**
+     * Top-level `fallback` has no calling field, so there is nothing to retry.
+     * Resolvers always receive a field-bound context whose `fallback` does retry;
+     * this entry exists only to satisfy the public {@link ResolverContext} shape.
+     */
+    fallback(_deps: Array<keyof Fields>): Promise<unknown>;
+    resolveMany<K extends keyof Fields>(...fields: K[]): Promise<Partial<Pick<Fields, K>>>;
+}
+
+export { GraphContext as G, type ResolverContext as R, type ResolverRegistry as a, type ResolverConfig as b, type ResolverFn as c, type ResolverSchemas as d };