@beignet/core 0.0.1

package/src/ports/unit-of-work.ts

@@ -0,0 +1,134 @@
+import { parseEventPayload } from "../events";
+import type { DomainEventDef, EventBusPort, InferEventPayload } from "./events";
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type UnitOfWorkCallback<TxPorts, Result> = (
+  tx: TxPorts,
+) => MaybePromise<Result>;
+
+/**
+ * A transaction boundary for application workflows.
+ *
+ * The transaction ports are app-owned. A database adapter can provide
+ * transaction-scoped repositories, while test or in-memory adapters can use
+ * `createNoopUnitOfWork`.
+ */
+export interface UnitOfWorkPort<TxPorts> {
+  transaction<Result>(
+    work: UnitOfWorkCallback<TxPorts, Result>,
+  ): Promise<Result>;
+}
+
+export interface NoopUnitOfWorkOptions<TxPorts> {
+  /**
+   * Runs after the callback completes successfully.
+   *
+   * Use this to flush buffered domain events after the work has committed.
+   */
+  afterCommit?: (tx: TxPorts) => MaybePromise<void>;
+
+  /**
+   * Runs after the callback throws.
+   *
+   * Use this to clear buffers or release test resources. The original error is
+   * rethrown after this hook runs.
+   */
+  afterRollback?: (error: unknown, tx: TxPorts) => MaybePromise<void>;
+}
+
+export interface RecordedDomainEvent {
+  event: DomainEventDef;
+  eventName: string;
+  payload: unknown;
+}
+
+export interface DomainEventRecorderPort {
+  record<E extends DomainEventDef>(
+    event: E,
+    payload: InferEventPayload<E>,
+  ): void;
+}
+
+export interface BufferedDomainEventRecorder extends DomainEventRecorderPort {
+  entries(): readonly RecordedDomainEvent[];
+  clear(): void;
+  flush(eventBus: EventBusPort): Promise<void>;
+}
+
+/**
+ * Create a simple Unit of Work implementation for tests, in-memory adapters,
+ * and infrastructure that already handles transactions elsewhere.
+ *
+ * This helper does not create database transactions. It gives applications the
+ * same UOW shape everywhere and runs commit/rollback hooks around the callback.
+ */
+export function createNoopUnitOfWork<TxPorts>(
+  txPortsOrFactory: TxPorts | (() => TxPorts),
+  options: NoopUnitOfWorkOptions<TxPorts> = {},
+): UnitOfWorkPort<TxPorts> {
+  const createTxPorts =
+    typeof txPortsOrFactory === "function"
+      ? (txPortsOrFactory as () => TxPorts)
+      : () => txPortsOrFactory;
+
+  return {
+    async transaction<Result>(
+      work: UnitOfWorkCallback<TxPorts, Result>,
+    ): Promise<Result> {
+      const tx = createTxPorts();
+
+      let result: Result;
+
+      try {
+        result = await work(tx);
+      } catch (error) {
+        try {
+          await options.afterRollback?.(error, tx);
+        } catch {
+          // Preserve the application error that caused the rollback path.
+        }
+
+        throw error;
+      }
+
+      await options.afterCommit?.(tx);
+      return result;
+    },
+  };
+}
+
+/**
+ * Buffer domain events during a transaction and publish them only after the
+ * owning Unit of Work commits.
+ */
+export function createDomainEventRecorder(): BufferedDomainEventRecorder {
+  const records: RecordedDomainEvent[] = [];
+
+  return {
+    record(event, payload) {
+      records.push({
+        event,
+        eventName: event.name,
+        payload,
+      });
+    },
+
+    entries() {
+      return records;
+    },
+
+    clear() {
+      records.length = 0;
+    },
+
+    async flush(eventBus) {
+      while (records.length > 0) {
+        const record = records[0];
+        const payload = await parseEventPayload(record.event, record.payload);
+        await eventBus.publish(record.event, payload);
+        records.shift();
+      }
+    },
+  };
+}

package/src/providers/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @beignet/core/providers
+ *
+ * Provider lifecycle and instrumentation primitives for Beignet.
+ */
+
+export {
+  type BaseProviderInstrumentationEvent,
+  type CustomProviderInstrumentationEvent,
+  createProviderInstrumentation,
+  type ErrorProviderInstrumentationEvent,
+  type EventBusProviderInstrumentationEvent,
+  isProviderInstrumentation,
+  isProviderInstrumentationPort,
+  type JobProviderInstrumentationEvent,
+  type ProviderCustomInstrumentationEventInput,
+  type ProviderInstrumentation,
+  type ProviderInstrumentationEvent,
+  type ProviderInstrumentationEventInput,
+  type ProviderInstrumentationOptions,
+  type ProviderInstrumentationPort,
+  type ProviderInstrumentationTarget,
+  type ProviderInstrumentationWatcherName,
+  type ProviderLifecycleInstrumentationEvent,
+  type RequestProviderInstrumentationEvent,
+  resolveProviderInstrumentationPort,
+  type ScheduleProviderInstrumentationEvent,
+  type UseCaseProviderInstrumentationEvent,
+} from "./instrumentation";
+export {
+  createProvider,
+  type InferOutput,
+  type MaybePromise,
+  type ProvidedPortsOf,
+  type ProvidedPortsOfList,
+  type ProviderConfigDef,
+  type ProviderLifecycleContext,
+  type ProviderSetupResult,
+  type ServiceProvider,
+} from "./provider";

package/src/providers/instrumentation.ts

@@ -0,0 +1,248 @@
+import { type Redactor, redactValue } from "../ports/redaction";
+
+export type ProviderInstrumentationWatcherName = string;
+
+export interface BaseProviderInstrumentationEvent {
+  id?: string;
+  timestamp?: string;
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+  watcher?: ProviderInstrumentationWatcherName;
+  details?: unknown;
+}
+
+export interface RequestProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "request";
+  method: string;
+  path: string;
+  contractName?: string;
+  status?: number;
+  durationMs?: number;
+  summary?: string;
+}
+
+export interface ErrorProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "error";
+  message: string;
+  stack?: string;
+  contractName?: string;
+  useCaseName?: string;
+}
+
+export interface UseCaseProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "usecase";
+  name: string;
+  kind?: "command" | "query";
+  phase: "start" | "end" | "error";
+  durationMs?: number;
+  error?: string;
+}
+
+export interface EventBusProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "eventBus";
+  eventName: string;
+}
+
+export interface JobProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "job";
+  jobName: string;
+  status: "scheduled" | "started" | "completed" | "failed";
+}
+
+export interface ScheduleProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "schedule";
+  scheduleName: string;
+  status: "started" | "completed" | "failed";
+  cron?: string;
+  timezone?: string;
+}
+
+export interface ProviderLifecycleInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "provider";
+  providerName: string;
+  action: "setup" | "start" | "stop";
+}
+
+export interface CustomProviderInstrumentationEvent
+  extends BaseProviderInstrumentationEvent {
+  type: "custom";
+  name: string;
+  label?: string;
+  summary?: string;
+}
+
+export type ProviderInstrumentationEvent =
+  | RequestProviderInstrumentationEvent
+  | ErrorProviderInstrumentationEvent
+  | UseCaseProviderInstrumentationEvent
+  | EventBusProviderInstrumentationEvent
+  | JobProviderInstrumentationEvent
+  | ScheduleProviderInstrumentationEvent
+  | ProviderLifecycleInstrumentationEvent
+  | CustomProviderInstrumentationEvent;
+
+export type ProviderInstrumentationEventInput = ProviderInstrumentationEvent;
+
+export type ProviderCustomInstrumentationEventInput = Omit<
+  CustomProviderInstrumentationEvent,
+  "type"
+>;
+
+export interface ProviderInstrumentationPort<
+  EventInput extends
+    ProviderInstrumentationEventInput = ProviderInstrumentationEventInput,
+  WatcherName extends string = ProviderInstrumentationWatcherName,
+  RecordResult = unknown,
+> {
+  record(event: EventInput): RecordResult;
+  isWatcherEnabled?(name: WatcherName): boolean;
+}
+
+export interface ProviderInstrumentationOptions {
+  providerName: string;
+  watcher?: ProviderInstrumentationWatcherName;
+  redact?: Redactor<ProviderInstrumentationEventInput>;
+}
+
+export interface ProviderInstrumentation {
+  port: ProviderInstrumentationPort | undefined;
+  isEnabled(watcher?: ProviderInstrumentationWatcherName): boolean;
+  record(event: ProviderInstrumentationEventInput): unknown;
+  custom(event: ProviderCustomInstrumentationEventInput): unknown;
+}
+
+export type ProviderInstrumentationTarget =
+  | ProviderInstrumentationPort
+  | ProviderInstrumentation
+  | {
+      devtools?: ProviderInstrumentationPort | ProviderInstrumentation;
+      instrumentation?: ProviderInstrumentationPort | ProviderInstrumentation;
+    }
+  | undefined;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function isProviderInstrumentation(
+  value: unknown,
+): value is ProviderInstrumentation {
+  return (
+    isObject(value) &&
+    typeof value.record === "function" &&
+    typeof value.custom === "function" &&
+    typeof value.isEnabled === "function"
+  );
+}
+
+export function isProviderInstrumentationPort(
+  value: unknown,
+): value is ProviderInstrumentationPort {
+  return isObject(value) && typeof value.record === "function";
+}
+
+function resolveProviderInstrumentationValue(
+  value: unknown,
+): ProviderInstrumentationPort | undefined {
+  if (isProviderInstrumentation(value)) return value.port;
+  if (isProviderInstrumentationPort(value)) return value;
+  return undefined;
+}
+
+export function resolveProviderInstrumentationPort(
+  target: ProviderInstrumentationTarget,
+): ProviderInstrumentationPort | undefined {
+  if (!target) return undefined;
+
+  const directPort = resolveProviderInstrumentationValue(target);
+  if (directPort) return directPort;
+
+  if (!isObject(target)) return undefined;
+
+  return (
+    resolveProviderInstrumentationValue(target.instrumentation) ??
+    resolveProviderInstrumentationValue(target.devtools)
+  );
+}
+
+function withProviderDetails(providerName: string, details: unknown): unknown {
+  if (details === undefined) {
+    return { providerName };
+  }
+
+  if (isObject(details) && !Array.isArray(details)) {
+    return { ...details, providerName };
+  }
+
+  return { providerName, value: details };
+}
+
+export function createProviderInstrumentation(
+  target: ProviderInstrumentationTarget,
+  options: ProviderInstrumentationOptions,
+): ProviderInstrumentation {
+  if (isProviderInstrumentation(target)) {
+    return target;
+  }
+
+  const port = resolveProviderInstrumentationPort(target);
+
+  function isEnabled(watcher = options.watcher): boolean {
+    if (!port) return false;
+    if (!watcher) return true;
+    return port.isWatcherEnabled?.(watcher) ?? true;
+  }
+
+  function record(event: ProviderInstrumentationEventInput): unknown {
+    if (!port) return undefined;
+
+    const watcher = event.watcher ?? options.watcher;
+    if (watcher && !isEnabled(watcher)) return undefined;
+
+    const eventWithWatcher =
+      options.watcher && event.watcher === undefined
+        ? { ...event, watcher: options.watcher }
+        : event;
+
+    let redacted: ProviderInstrumentationEventInput;
+    try {
+      redacted = options.redact
+        ? options.redact(redactValue(eventWithWatcher))
+        : redactValue(eventWithWatcher);
+    } catch {
+      return undefined;
+    }
+
+    try {
+      return port.record(redacted);
+    } catch {
+      return undefined;
+    }
+  }
+
+  function custom(event: ProviderCustomInstrumentationEventInput): unknown {
+    return record({
+      ...event,
+      type: "custom",
+      watcher: event.watcher ?? options.watcher,
+      details: withProviderDetails(options.providerName, event.details),
+    });
+  }
+
+  return {
+    port,
+    isEnabled,
+    record,
+    custom,
+  };
+}

package/src/providers/provider.ts

@@ -0,0 +1,191 @@
+/**
+ * Provider system for Beignet
+ *
+ * Providers are modular extensions that can add new ports or replace existing ones
+ * during application initialization. They support configuration via Standard Schema
+ * and optional lifecycle hooks.
+ */
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+type ProviderPorts = Record<string, unknown>;
+declare const noProvidedPorts: unique symbol;
+type NoProvidedPorts = { [noProvidedPorts]?: never };
+
+/**
+ * Extract the output type from a Standard Schema.
+ * This is the validated/parsed type that results from schema validation.
+ */
+export type InferOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Configuration definition for a service provider.
+ * Specifies the schema for validating config and optional environment variable prefix.
+ */
+export interface ProviderConfigDef<CfgSchema extends StandardSchemaV1> {
+  /**
+   * Standard Schema for validating provider configuration.
+   * Can be Zod, Valibot, ArkType, or any Standard Schema compatible library.
+   */
+  schema: CfgSchema;
+
+  /**
+   * Optional prefix to read env vars, e.g. "REDIS_".
+   * When provided, the implementation will read process.env keys starting with this prefix
+   * and pass them to the schema for validation.
+   */
+  envPrefix?: string;
+}
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type ProviderLifecycleContext = {
+  ports: Readonly<ProviderPorts>;
+};
+
+export type ProviderSetupResult<ProvidedPorts extends ProviderPorts> = {
+  /**
+   * Ports contributed by this provider.
+   * Keys overwrite earlier ports with the same name at runtime. Prefer unique
+   * keys unless the replacement implements the same port contract.
+   */
+  ports?: ProvidedPorts;
+
+  /**
+   * Optional hook called after all providers have contributed their ports.
+   */
+  start?: (ctx: ProviderLifecycleContext) => MaybePromise<void>;
+
+  /**
+   * Optional hook called when the server is stopped.
+   */
+  stop?: (ctx: ProviderLifecycleContext) => MaybePromise<void>;
+};
+
+/**
+ * A service provider that can extend or replace ports during app initialization.
+ *
+ * Providers support:
+ * - Configuration via Standard Schema (any compatible library: Zod, Valibot, etc.)
+ * - Returning ports with new capabilities (e.g., cache, mailer)
+ * - Replacing existing ports by returning the same key
+ * - Optional start/stop hooks
+ *
+ * @example
+ * ```ts
+ * const redisProvider = createProvider({
+ *   name: "redis",
+ *   config: {
+ *     schema: z.object({ URL: z.string().url() }),
+ *     envPrefix: "REDIS_",
+ *   },
+ *   async setup({ config }) {
+ *     const client = new Redis(config.URL);
+ *     return {
+ *       ports: {
+ *         cache: {
+ *           get: (key) => client.get(key),
+ *           set: (key, value) => client.set(key, value),
+ *         },
+ *       },
+ *       stop: () => client.quit(),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export interface ServiceProvider<
+  Ports,
+  CfgSchema extends StandardSchemaV1 = StandardSchemaV1<void, void>,
+  ProvidedPorts extends ProviderPorts = NoProvidedPorts,
+> {
+  /**
+   * Unique name for this provider (used for logging/debugging)
+   */
+  name: string;
+
+  /**
+   * Optional configuration definition.
+   * If provided, the config will be loaded and validated before calling setup.
+   */
+  config?: ProviderConfigDef<CfgSchema>;
+
+  /**
+   * Setup phase: create the ports this provider contributes.
+   * Called during app initialization, before routes are registered.
+   *
+   * @param ctx.ports - Ports contributed by previous providers
+   * @param ctx.config - Validated config (if config was defined), or undefined
+   */
+  setup(ctx: {
+    ports: Readonly<Ports>;
+    config: InferOutput<CfgSchema> | undefined;
+  }): MaybePromise<ProviderSetupResult<ProvidedPorts>>;
+
+  /**
+   * Type-only marker for ports this provider contributes.
+   * Runtime provider objects do not need to set this property.
+   */
+  readonly __providedPorts?: ProvidedPorts;
+}
+
+/**
+ * Extract the ports a provider contributes.
+ */
+export type ProvidedPortsOf<TProvider> =
+  TProvider extends ServiceProvider<
+    infer _Ports,
+    infer _CfgSchema,
+    infer ProvidedPorts
+  >
+    ? ProvidedPorts
+    : NoProvidedPorts;
+
+type UnionToIntersection<T> = (
+  T extends unknown
+    ? (value: T) => void
+    : never
+) extends (value: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Extract and merge the ports contributed by a provider list.
+ */
+export type ProvidedPortsOfList<TProviders> =
+  TProviders extends readonly unknown[]
+    ? [TProviders[number]] extends [never]
+      ? NoProvidedPorts
+      : UnionToIntersection<ProvidedPortsOf<TProviders[number]>>
+    : NoProvidedPorts;
+
+/**
+ * Helper function to create a provider with proper type inference.
+ *
+ * This is a simple identity function that helps TypeScript infer the correct types
+ * for the provider definition.
+ *
+ * @example
+ * ```ts
+ * export const myProvider = createProvider({
+ *   name: "my-provider",
+ *   config: {
+ *     schema: z.object({ apiKey: z.string() }),
+ *     envPrefix: "MY_SERVICE_",
+ *   },
+ *   async setup({ config }) {
+ *     return { ports: { myService: createMyService(config) } };
+ *   },
+ * });
+ * ```
+ */
+export function createProvider<
+  Ports = unknown,
+  CfgSchema extends StandardSchemaV1 = StandardSchemaV1<void, void>,
+  ProvidedPorts extends ProviderPorts = NoProvidedPorts,
+>(
+  def: ServiceProvider<Ports, CfgSchema, ProvidedPorts>,
+): ServiceProvider<Ports, CfgSchema, ProvidedPorts> {
+  return def;
+}