@beignet/core 0.0.30 → 0.0.32

package/src/memo/index.ts

@@ -0,0 +1,310 @@
+/**
+ * @beignet/core/memo
+ *
+ * Request-scoped memoization for port lookups and other async functions.
+ *
+ * `createMemo(fn)` deduplicates calls with the same arguments for the
+ * lifetime of one request: the server enters a memo scope around every HTTP
+ * request and `runServiceContext(...)` execution, and the scope's cache dies
+ * with it. There is no TTL and no cross-request state, so memoized reads can
+ * never serve data staler than the request that fetched them.
+ *
+ * Outside any scope — plain scripts, `createServiceContext(...)` callers —
+ * memoized functions call straight through without caching.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Error thrown when a default cache key cannot be derived from arguments.
+ */
+export class MemoKeyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MemoKeyError";
+  }
+}
+
+/**
+ * Instrumentation event emitted by memoized functions inside a scope that
+ * carries a recorder.
+ */
+export interface MemoInstrumentationEvent {
+  /** Whether the call was served from the scope cache or filled it. */
+  kind: "hit" | "miss";
+  /** Memo name from `createMemo` options, defaulting to the function name. */
+  memo: string;
+  /** Encoded argument key for the call. */
+  key: string;
+  /** Fill duration for misses, rounded to two decimals. */
+  durationMs?: number;
+  /** Set when a miss's underlying call rejected (the entry is evicted). */
+  failed?: boolean;
+}
+
+type MemoScopeStore = {
+  entries: Map<string, unknown>;
+  record?: (event: MemoInstrumentationEvent) => void;
+};
+
+const memoScope = new AsyncLocalStorage<MemoScopeStore>();
+
+/**
+ * Run a function inside a memo scope with an explicit recorder.
+ *
+ * Internal to the server runtime — apps should use `runMemoScope(...)`.
+ * Always uses `AsyncLocalStorage.run` (never `enterWith`), so callers'
+ * continuations never resume through a dangling frame.
+ */
+export function runWithMemoScope<T>(
+  options: { record?: (event: MemoInstrumentationEvent) => void },
+  fn: () => T,
+): T {
+  return memoScope.run({ entries: new Map(), record: options.record }, fn);
+}
+
+/**
+ * Run a function inside a fresh memo scope.
+ *
+ * Use this in scripts and unit tests to give memoized functions a cache
+ * lifetime. Nested scopes start empty; an active recorder is inherited so
+ * instrumentation keeps flowing.
+ */
+export function runMemoScope<T>(fn: () => T): T {
+  return runWithMemoScope({ record: memoScope.getStore()?.record }, fn);
+}
+
+/**
+ * Memoized function returned by `createMemo(...)`.
+ */
+export type Memoized<F extends (...args: never[]) => unknown> = F & {
+  /**
+   * Drop the current scope's entry for these arguments, so the next call
+   * re-executes. Call this from mutation methods that make a memoized read
+   * stale within the same request.
+   *
+   * @returns Whether an entry existed.
+   */
+  invalidate(...args: Parameters<F>): boolean;
+  /**
+   * Drop all of this function's entries in the current scope.
+   */
+  clear(): void;
+};
+
+/**
+ * Options for `createMemo(...)`.
+ */
+export interface CreateMemoOptions<F extends (...args: never[]) => unknown> {
+  /**
+   * Name used in instrumentation events and key errors. Defaults to the
+   * wrapped function's name.
+   */
+  name?: string;
+  /**
+   * Build the cache key from the call arguments. Defaults to a structural,
+   * type-tagged encoding of the arguments that throws `MemoKeyError` for
+   * values it cannot encode deterministically (functions, symbols, class
+   * instances, circular references).
+   */
+  key?: (...args: Parameters<F>) => string;
+}
+
+type EncodedMemoValue = readonly [string, ...unknown[]];
+
+function describeArgType(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value !== "object") return typeof value;
+  const ctor = (value as object).constructor?.name;
+  return ctor && ctor !== "Object" ? `class instance (${ctor})` : "object";
+}
+
+function encodeMemoValue(
+  value: unknown,
+  memoName: string,
+  position: number,
+  seen: WeakSet<object>,
+): EncodedMemoValue {
+  if (value === null) return ["null"];
+
+  switch (typeof value) {
+    case "string":
+      return ["string", value];
+    case "number":
+      return ["number", Object.is(value, -0) ? "-0" : String(value)];
+    case "boolean":
+      return ["boolean", value ? "true" : "false"];
+    case "undefined":
+      return ["undefined"];
+    case "bigint":
+      return ["bigint", value.toString()];
+    case "object":
+      break;
+    default:
+      throw new MemoKeyError(
+        `[Beignet memo] Cannot build a default cache key for "${memoName}": argument ${position} is a ${typeof value}. Pass options.key to compute keys for these arguments.`,
+      );
+  }
+
+  if (value instanceof Date) {
+    return ["date", value.toISOString()];
+  }
+
+  if (seen.has(value as object)) {
+    throw new MemoKeyError(
+      `[Beignet memo] Cannot build a default cache key for "${memoName}": argument ${position} contains a circular reference. Pass options.key to compute keys for these arguments.`,
+    );
+  }
+
+  if (Array.isArray(value)) {
+    seen.add(value);
+    const encoded: EncodedMemoValue = [
+      "array",
+      value.map((item) => encodeMemoValue(item, memoName, position, seen)),
+    ];
+    seen.delete(value);
+    return encoded;
+  }
+
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== null && proto !== Object.prototype) {
+    throw new MemoKeyError(
+      `[Beignet memo] Cannot build a default cache key for "${memoName}": argument ${position} is a ${describeArgType(value)}. Pass options.key to compute keys for these arguments.`,
+    );
+  }
+
+  seen.add(value as object);
+  const record = value as Record<string, unknown>;
+  const encoded: EncodedMemoValue = [
+    "object",
+    Object.keys(record)
+      .sort()
+      .map((key) => [
+        key,
+        encodeMemoValue(record[key], memoName, position, seen),
+      ]),
+  ];
+  seen.delete(value as object);
+  return encoded;
+}
+
+function defaultArgsKey(memoName: string, args: readonly unknown[]): string {
+  return JSON.stringify(
+    args.map((arg, index) =>
+      encodeMemoValue(arg, memoName, index, new WeakSet()),
+    ),
+  );
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function roundDuration(startedAt: number): number {
+  return Math.round((performance.now() - startedAt) * 100) / 100;
+}
+
+let nextMemoInstance = 0;
+
+/**
+ * Wrap an async lookup so calls with the same arguments run once per request.
+ *
+ * Within a memo scope the first call executes and every later call with the
+ * same key returns the same value — including the same in-flight promise, so
+ * concurrent calls share one execution. Rejected promises are evicted, so a
+ * failed lookup is retried by the next call rather than memoized. Outside a
+ * scope the function calls through uncached.
+ *
+ * Memoize reads, not mutations. When a mutation in the same infra module
+ * makes a memoized read stale, call `memoized.invalidate(...)` with the
+ * read's arguments.
+ *
+ * @param fn - Function to memoize. `this` is not forwarded.
+ * @param options - Optional name and key builder.
+ * @returns The function with `invalidate(...)` and `clear()` attached.
+ */
+export function createMemo<F extends (...args: never[]) => unknown>(
+  fn: F,
+  options: CreateMemoOptions<F> = {},
+): Memoized<F> {
+  const name = options.name ?? (fn.name || "anonymous");
+  // The map key is namespaced by instance, not name, so two memos that share
+  // a name can never read each other's entries. The unit separator keeps
+  // prefixes unambiguous: instance 1 never prefix-matches instance 11.
+  nextMemoInstance += 1;
+  const instancePrefix = `${nextMemoInstance}\u001f`;
+  const keyOf = (args: Parameters<F>): string =>
+    options.key ? options.key(...args) : defaultArgsKey(name, args);
+
+  const memoized = ((...args: Parameters<F>): unknown => {
+    const store = memoScope.getStore();
+    if (!store) return fn(...args);
+
+    const argsKey = keyOf(args);
+    const mapKey = instancePrefix + argsKey;
+    if (store.entries.has(mapKey)) {
+      store.record?.({ kind: "hit", memo: name, key: argsKey });
+      return store.entries.get(mapKey);
+    }
+
+    const startedAt = performance.now();
+    const value = fn(...args);
+    store.entries.set(mapKey, value);
+
+    if (isPromiseLike(value)) {
+      Promise.resolve(value).then(
+        () => {
+          store.record?.({
+            kind: "miss",
+            memo: name,
+            key: argsKey,
+            durationMs: roundDuration(startedAt),
+          });
+        },
+        () => {
+          if (store.entries.get(mapKey) === value) {
+            store.entries.delete(mapKey);
+          }
+          store.record?.({
+            kind: "miss",
+            memo: name,
+            key: argsKey,
+            durationMs: roundDuration(startedAt),
+            failed: true,
+          });
+        },
+      );
+    } else {
+      store.record?.({
+        kind: "miss",
+        memo: name,
+        key: argsKey,
+        durationMs: roundDuration(startedAt),
+      });
+    }
+
+    return value;
+  }) as Memoized<F>;
+
+  memoized.invalidate = (...args: Parameters<F>): boolean => {
+    const store = memoScope.getStore();
+    if (!store) return false;
+    return store.entries.delete(instancePrefix + keyOf(args));
+  };
+
+  memoized.clear = (): void => {
+    const store = memoScope.getStore();
+    if (!store) return;
+    for (const key of [...store.entries.keys()]) {
+      if (key.startsWith(instancePrefix)) {
+        store.entries.delete(key);
+      }
+    }
+  };
+
+  return memoized;
+}

package/src/outbox/index.ts

@@ -16,6 +16,8 @@ import {
   type InferJobPayload,
   type JobDef,
   parseJobPayload,
+  SINGLE_ATTEMPT_DISPATCH,
+  type SingleAttemptJobDispatch,
   shouldRetryJob,
 } from "../jobs/index.js";
 import type { JobDispatcherPort } from "../ports/events.js";
@@ -311,9 +313,13 @@ export interface MemoryOutboxPort extends OutboxPort {
  */
 export interface CreateOutboxMessageOptions {
   /**
-   * Generated message ID override.
+   * Generated message ID override. Wins over `input.id`.
    */
   id?: string;
+  /**
+   * Fallback ID factory used when neither `id` nor `input.id` is provided.
+   */
+  createId?: () => string;
   /**
    * Timestamp used for created/updated/available dates.
    */
@@ -677,7 +683,7 @@ export function createOutboxMessage(
 
   const now = options.now ?? new Date();
   return {
-    id: options.id ?? input.id ?? createId(),
+    id: options.id ?? input.id ?? options.createId?.() ?? createId(),
     kind: input.kind,
     name: input.name,
     payload: toOutboxJsonValue(input.payload),
@@ -709,12 +715,31 @@ function isEligible(message: OutboxMessage, now: Date): boolean {
   );
 }
 
+/**
+ * Options for `createMemoryOutbox(...)`.
+ */
+export interface MemoryOutboxOptions {
+  /**
+   * Message and claim-token ID factory. Defaults to `crypto.randomUUID()`.
+   */
+  id?: () => string;
+  /**
+   * Clock used for enqueue, claim, and completion timestamps when a call does
+   * not supply its own `now`. Defaults to the system clock.
+   */
+  now?: () => Date;
+}
+
 /**
  * Create an in-memory outbox for tests and local examples.
  *
  * The memory outbox is process-local and not durable.
  */
-export function createMemoryOutbox(): MemoryOutboxPort {
+export function createMemoryOutbox(
+  storeOptions: MemoryOutboxOptions = {},
+): MemoryOutboxPort {
+  const createStoreId = storeOptions.id ?? createId;
+  const storeNow = storeOptions.now ?? (() => new Date());
   const messages = new Map<string, OutboxMessage>();
 
   function getClaimedOrThrow(id: string, claimToken: string): OutboxMessage {
@@ -740,7 +765,10 @@ export function createMemoryOutbox(): MemoryOutboxPort {
     },
 
     async enqueue(input) {
-      const message = createOutboxMessage(input);
+      const message = createOutboxMessage(input, {
+        createId: createStoreId,
+        now: storeNow(),
+      });
       if (messages.has(message.id)) {
         throw new Error(`Outbox message "${message.id}" already exists.`);
       }
@@ -750,7 +778,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
 
     async claimBatch(options) {
       assertPositiveInteger("limit", options.limit);
-      const now = options.now ?? new Date();
+      const now = options.now ?? storeNow();
       const leaseMs = options.leaseMs ?? DEFAULT_OUTBOX_LEASE_MS;
       assertPositiveInteger("leaseMs", leaseMs);
       const lockedUntil = new Date(now.getTime() + leaseMs);
@@ -768,7 +796,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
       for (const message of eligible) {
         message.status = "claimed";
         message.attempts += 1;
-        message.claimToken = createId();
+        message.claimToken = createStoreId();
         message.claimedAt = cloneDate(now);
         message.lockedUntil = cloneDate(lockedUntil);
         message.updatedAt = cloneDate(now);
@@ -782,7 +810,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
       assertNonEmptyString("id", input.id);
       assertNonEmptyString("claimToken", input.claimToken);
       const message = getClaimedOrThrow(input.id, input.claimToken);
-      const now = input.now ?? new Date();
+      const now = input.now ?? storeNow();
 
       message.status = "delivered";
       message.deliveredAt = cloneDate(now);
@@ -796,7 +824,7 @@ export function createMemoryOutbox(): MemoryOutboxPort {
       assertNonEmptyString("id", input.id);
       assertNonEmptyString("claimToken", input.claimToken);
       const message = getClaimedOrThrow(input.id, input.claimToken);
-      const now = input.now ?? new Date();
+      const now = input.now ?? storeNow();
 
       message.status = input.deadLetter ? "deadLettered" : "pending";
       message.lastError = serializeOutboxError(input.error);
@@ -1018,6 +1046,22 @@ async function deliverOutboxMessage(
   }
 
   const payload = await parseJobPayload(job, message.payload);
+
+  // The drain owns execution retries: failed deliveries are rescheduled with
+  // the job's own policy via markFailed/retryAt. When the dispatcher exposes
+  // a single-attempt dispatch (the inline dispatcher does), use it so the
+  // retry policy runs in exactly one layer. Durable providers do not expose
+  // it — for them dispatch is an enqueue and the queue owns execution.
+  const singleAttempt = (
+    options.jobs as {
+      [SINGLE_ATTEMPT_DISPATCH]?: SingleAttemptJobDispatch;
+    }
+  )[SINGLE_ATTEMPT_DISPATCH];
+  if (singleAttempt) {
+    await singleAttempt(job, payload);
+    return;
+  }
+
   await options.jobs.dispatch(job, payload);
 }
 

package/src/ports/events.ts

@@ -10,8 +10,8 @@ import type {
 
 /**
  * Represents a defined Domain Event with name and payload schema.
- * This is a minimal interface that ports need - implementations can use
- * the full DomainEventDef from @beignet/core/domain if desired.
+ * This is a minimal structural interface that ports need - event
+ * declarations from `defineEvent` in @beignet/core/events satisfy it.
  */
 export interface DomainEventDef<
   Name extends string = string,

package/src/providers/provider.ts

@@ -36,6 +36,15 @@ export interface ProviderConfigDef<CfgSchema extends StandardSchemaV1> {
    * and pass them to the schema for validation.
    */
   envPrefix?: string;
+
+  /**
+   * Field-level config overrides, keyed by schema field name. Defined values
+   * are merged over the env-derived (or server-supplied) input before
+   * validation, so factory options win over environment variables and still
+   * satisfy required fields when the env var is absent. `undefined` values
+   * are ignored.
+   */
+  overrides?: Record<string, unknown>;
 }
 
 /**
@@ -161,8 +170,8 @@ export interface ServiceProviderMetadata {
  *
  * @example
  * ```ts
- * const redisProvider = createProvider({
- *   name: "redis",
+ * const redisCacheProvider = createProvider({
+ *   name: "cache-redis",
  *   config: {
  *     schema: z.object({ URL: z.string().url() }),
  *     envPrefix: "REDIS_",

package/src/search/index.ts

@@ -47,6 +47,7 @@ type SearchField<TDocument extends SearchDocumentBase> = Extract<
 export type SearchIndexDef<
   TDocument extends SearchDocumentBase = SearchDocument,
 > = {
+  kind: "search-index";
   name: string;
   primaryKey: SearchField<TDocument>;
   searchableAttributes?: readonly SearchField<TDocument>[];
@@ -60,7 +61,7 @@ export type SearchIndexDef<
  * Options accepted when defining a search index.
  */
 export type DefineSearchIndexOptions<TDocument extends SearchDocumentBase> =
-  Omit<SearchIndexDef<TDocument>, "name" | "primaryKey"> & {
+  Omit<SearchIndexDef<TDocument>, "kind" | "name" | "primaryKey"> & {
     primaryKey?: SearchField<TDocument>;
   };
 
@@ -216,6 +217,7 @@ export function defineSearchIndex<
   if (!name) throw new SearchOptionsError("Search index name is required.");
 
   return {
+    kind: "search-index",
     name,
     primaryKey: options.primaryKey ?? ("id" as SearchField<TDocument>),
     searchableAttributes: options.searchableAttributes,

package/src/server/providers/loadProviderConfig.ts

@@ -11,6 +11,7 @@ import type { ServiceProvider } from "../../providers/index.js";
 type ProviderConfigDef<Schema extends StandardSchemaV1<unknown, unknown>> = {
   schema: Schema;
   envPrefix?: string;
+  overrides?: Record<string, unknown>;
 };
 
 async function parseStandardSchema<
@@ -47,14 +48,30 @@ export async function loadProviderConfig<
   const configDef = provider.config as ProviderConfigDef<Schema> | undefined;
   if (!configDef) return undefined;
 
-  const { schema, envPrefix } = configDef;
+  const { schema, envPrefix, overrides: fieldOverrides } = configDef;
   const hasOverride = Object.hasOwn(overrides, provider.name);
-  const input = hasOverride
+  const base = hasOverride
     ? overrides[provider.name]
     : envPrefix
       ? readEnv({ env, prefix: envPrefix })
       : {};
 
+  // Field-level overrides from the provider's own config definition (factory
+  // options) win over env-derived and server-supplied values. Defined values
+  // only, so absent options fall back to the base input and schema defaults.
+  let input = base;
+  if (fieldOverrides) {
+    const defined = Object.fromEntries(
+      Object.entries(fieldOverrides).filter(([, value]) => value !== undefined),
+    );
+    if (Object.keys(defined).length > 0) {
+      input = {
+        ...(typeof base === "object" && base !== null ? base : {}),
+        ...defined,
+      };
+    }
+  }
+
   try {
     return await parseStandardSchema(schema, input);
   } catch (error) {

package/src/server/server.ts

@@ -24,6 +24,10 @@ import {
   IdempotencyConflictError,
   IdempotencyInProgressError,
 } from "../idempotency/index.js";
+import {
+  type MemoInstrumentationEvent,
+  runWithMemoScope,
+} from "../memo/index.js";
 import type { AnyPorts } from "../ports/index.js";
 import {
   AuthUnauthorizedError,
@@ -32,10 +36,13 @@ import {
   isUnboundPort,
   TenantRequiredError,
 } from "../ports/index.js";
-import type {
-  InferProviderPorts,
-  ProviderSetupResult,
-  ServiceProvider,
+import {
+  createProviderInstrumentation,
+  type InferProviderPorts,
+  type ProviderInstrumentationTarget,
+  type ProviderSetupResult,
+  resolveProviderInstrumentationPort,
+  type ServiceProvider,
 } from "../providers/index.js";
 import type {
   ContextSeed,
@@ -2126,6 +2133,41 @@ function createRequestExecutor<
   };
 }
 
+/**
+ * Build a memo instrumentation recorder from the app ports, or undefined when
+ * no instrumentation sink is wired.
+ *
+ * Resolved per execution rather than at route-build time because providers
+ * contribute `ports.instrumentation`/`ports.devtools` during setup, after
+ * routes are registered.
+ */
+function createMemoScopeRecorder(
+  ports: AnyPorts,
+): ((event: MemoInstrumentationEvent) => void) | undefined {
+  const target = ports as ProviderInstrumentationTarget;
+  if (!resolveProviderInstrumentationPort(target)) return undefined;
+
+  const instrumentation = createProviderInstrumentation(target, {
+    providerName: "memo",
+    watcher: "memo",
+  });
+  return (event) => {
+    instrumentation.custom({
+      name: `memo.${event.kind}`,
+      label: event.kind === "hit" ? "Memo hit" : "Memo fill",
+      summary: `Memo ${event.kind} for ${event.memo}`,
+      details: {
+        memo: event.memo,
+        key: event.key,
+        ...(event.durationMs !== undefined
+          ? { durationMs: event.durationMs }
+          : {}),
+        ...(event.failed ? { failed: true } : {}),
+      },
+    });
+  };
+}
+
 function buildHandler<
   Ctx,
   Ports extends AnyPorts,
@@ -2177,8 +2219,12 @@ function buildHandler<
     responseValidationExemptStatus,
   };
 
+  // Every HTTP execution runs inside a fresh memo scope so createMemo(...)
+  // wrappers dedupe lookups for exactly one request.
   return (req, preMatchedParams) =>
-    execute(executionTarget, req, preMatchedParams);
+    runWithMemoScope({ record: createMemoScopeRecorder(finalPorts) }, () =>
+      execute(executionTarget, req, preMatchedParams),
+    );
 }
 
 /**
@@ -2322,19 +2368,28 @@ export async function createServer<
     // AsyncLocalStorage.run scopes the ambient frame to this callback, so the
     // caller's continuation never resumes through an enterWith frame — the
     // pattern that crashes Bun 1.3.x in plain scripts under top-level await.
-    return runWithActiveRequestContext(ambient, async () => {
-      const ctx = finalizeContext(
-        await serviceFactory({
-          ports: finalPorts,
-          input,
-          requestId,
-          trace,
-        }),
-      );
-      ambient.actor = readContextActor(ctx);
-      ambient.tenant = readContextTenant(ctx);
-      return await fn(ctx);
-    });
+    // The memo scope shares the callback's lifetime, so createMemo(...)
+    // wrappers dedupe lookups across the context factory and fn. The
+    // createServiceContext(...) form has no such boundary and stays
+    // unscoped: memoized functions call through uncached there.
+    return runWithActiveRequestContext(ambient, () =>
+      runWithMemoScope(
+        { record: createMemoScopeRecorder(finalPorts) },
+        async () => {
+          const ctx = finalizeContext(
+            await serviceFactory({
+              ports: finalPorts,
+              input,
+              requestId,
+              trace,
+            }),
+          );
+          ambient.actor = readContextActor(ctx);
+          ambient.tenant = readContextTenant(ctx);
+          return await fn(ctx);
+        },
+      ),
+    );
   };
   const contextRuntime = {
     createRequestContext,