@beignet/core 0.0.1

package/src/openapi/schema-introspector.ts

@@ -0,0 +1,107 @@
+/**
+ * Schema introspection adapter.
+ *
+ * Abstracts the details of reading metadata from a schema library (e.g. Zod)
+ * so that the OpenAPI generator is not directly coupled to `_def` internals.
+ *
+ * A default Zod implementation is provided via `createZodIntrospector()`.
+ * To support a different schema library, implement this interface.
+ */
+export interface SchemaIntrospector {
+  /**
+   * Extract the shape (field name → field schema) from an object schema.
+   * Returns undefined if the schema is not an object type or cannot be inspected.
+   */
+  getShape(schema: unknown): Record<string, unknown> | undefined;
+
+  /**
+   * Extract the user-supplied `.describe()` string from a schema.
+   */
+  getDescription(schema: unknown): string | undefined;
+
+  /**
+   * Return true if the schema represents an optional wrapper.
+   */
+  isOptional(schema: unknown): boolean;
+
+  /**
+   * If the schema is an optional wrapper, return the inner (unwrapped) schema.
+   * Otherwise return the original schema unchanged.
+   */
+  unwrapOptional(schema: unknown): unknown;
+}
+
+/**
+ * Create a schema introspector for Zod schemas.
+ *
+ * This accesses Zod's internal `_def` property, which is a common pattern in
+ * Zod ecosystem libraries but may break with major Zod updates. Each helper
+ * gracefully returns a safe default if the structure is unexpected.
+ */
+export function createZodIntrospector(): SchemaIntrospector {
+  return {
+    getShape(schema: unknown): Record<string, unknown> | undefined {
+      if (!schema || typeof schema !== "object") return undefined;
+
+      const schemaDef = (schema as Record<string, unknown>)?._def;
+      if (!schemaDef || typeof schemaDef !== "object") return undefined;
+
+      if (!("shape" in schemaDef)) return undefined;
+
+      let shape: unknown;
+      if (typeof schemaDef.shape === "function") {
+        shape = schemaDef.shape();
+      } else if (typeof schemaDef.shape === "object") {
+        shape = schemaDef.shape;
+      }
+
+      if (!shape || typeof shape !== "object") return undefined;
+
+      return shape as Record<string, unknown>;
+    },
+
+    getDescription(schema: unknown): string | undefined {
+      if (!schema || typeof schema !== "object") return undefined;
+
+      const directDescription = (schema as { description?: unknown })
+        .description;
+      if (typeof directDescription === "string") {
+        return directDescription;
+      }
+
+      const schemaDef = (schema as Record<string, unknown>)?._def;
+      if (!schemaDef || typeof schemaDef !== "object") return undefined;
+
+      const description = (schemaDef as Record<string, unknown>).description;
+      return typeof description === "string" ? description : undefined;
+    },
+
+    isOptional(schema: unknown): boolean {
+      if (!schema || typeof schema !== "object") return false;
+
+      const schemaWithOptional = schema as {
+        isOptional?: () => boolean;
+      };
+      if (typeof schemaWithOptional.isOptional === "function") {
+        return schemaWithOptional.isOptional();
+      }
+
+      const schemaDef = (schema as Record<string, unknown>)?._def;
+      if (!schemaDef || typeof schemaDef !== "object") return false;
+
+      const def = schemaDef as Record<string, unknown>;
+      return def.typeName === "ZodOptional" || def.type === "optional";
+    },
+
+    unwrapOptional(schema: unknown): unknown {
+      const schemaDef = (schema as Record<string, unknown>)?._def;
+      const def = schemaDef as Record<string, unknown> | undefined;
+      if (def?.typeName !== "ZodOptional" && def?.type !== "optional") {
+        return schema;
+      }
+
+      const innerType = def?.innerType;
+      return innerType ?? schema;
+    },
+  };
+}

package/src/ports/audit.ts

@@ -0,0 +1,176 @@
+import { redactValue } from "./redaction";
+
+export type ActivityActorType = "anonymous" | "service" | "system" | "user";
+
+export type AuditOutcome = "success" | "failure";
+
+export type ActivityMetadataValue =
+  | ActivityMetadataValue[]
+  | boolean
+  | null
+  | number
+  | string
+  | { [key: string]: ActivityMetadataValue | undefined };
+
+export type ActivityMetadata = Record<
+  string,
+  ActivityMetadataValue | undefined
+>;
+
+export interface ActivityActor {
+  type: ActivityActorType;
+  id?: string;
+  displayName?: string;
+  metadata?: ActivityMetadata;
+}
+
+export interface ActivityTenant {
+  id: string;
+  slug?: string;
+  metadata?: ActivityMetadata;
+}
+
+export interface ActivityResource {
+  type: string;
+  id?: string;
+  name?: string;
+  metadata?: ActivityMetadata;
+}
+
+export interface AuditLogEntry {
+  action: string;
+  actor: ActivityActor;
+  occurredAt: Date;
+  outcome: AuditOutcome;
+  metadata?: ActivityMetadata;
+  message?: string;
+  requestId?: string;
+  resource?: ActivityResource;
+  tenant?: ActivityTenant;
+  traceId?: string;
+}
+
+export type AuditLogEntryInput = Omit<
+  AuditLogEntry,
+  "occurredAt" | "outcome"
+> & {
+  occurredAt?: Date;
+  outcome?: AuditOutcome;
+};
+
+export interface AuditLogPort {
+  record(entry: AuditLogEntryInput): Promise<void> | void;
+}
+
+export interface MemoryAuditLogPort extends AuditLogPort {
+  entries: AuditLogEntry[];
+}
+
+export interface AuditLogOptions {
+  redact?: (entry: AuditLogEntry) => AuditLogEntry;
+}
+
+export function createAnonymousActor(
+  options: Omit<ActivityActor, "type"> = {},
+): ActivityActor {
+  return { type: "anonymous", ...options };
+}
+
+export function createServiceActor(
+  id: string,
+  options: Omit<ActivityActor, "type" | "id"> = {},
+): ActivityActor {
+  return { type: "service", id, ...options };
+}
+
+export function createSystemActor(
+  id = "system",
+  options: Omit<ActivityActor, "type" | "id"> = {},
+): ActivityActor {
+  return { type: "system", id, ...options };
+}
+
+export function createUserActor(
+  id: string,
+  options: Omit<ActivityActor, "type" | "id"> = {},
+): ActivityActor {
+  return { type: "user", id, ...options };
+}
+
+export function createTenant(
+  id: string,
+  options: Omit<ActivityTenant, "id"> = {},
+): ActivityTenant {
+  return { id, ...options };
+}
+
+export function normalizeAuditLogEntry(
+  entry: AuditLogEntryInput,
+): AuditLogEntry {
+  return {
+    ...entry,
+    occurredAt: entry.occurredAt ?? new Date(),
+    outcome: entry.outcome ?? "success",
+  };
+}
+
+export function redactAuditLogEntry(entry: AuditLogEntry): AuditLogEntry {
+  return {
+    ...entry,
+    actor: {
+      ...entry.actor,
+      metadata: entry.actor.metadata
+        ? redactValue(entry.actor.metadata)
+        : entry.actor.metadata,
+    },
+    tenant: entry.tenant
+      ? {
+          ...entry.tenant,
+          metadata: entry.tenant.metadata
+            ? redactValue(entry.tenant.metadata)
+            : entry.tenant.metadata,
+        }
+      : entry.tenant,
+    resource: entry.resource
+      ? {
+          ...entry.resource,
+          metadata: entry.resource.metadata
+            ? redactValue(entry.resource.metadata)
+            : entry.resource.metadata,
+        }
+      : entry.resource,
+    metadata: entry.metadata ? redactValue(entry.metadata) : entry.metadata,
+  };
+}
+
+export function createRedactedAuditLog(
+  audit: AuditLogPort,
+  options: AuditLogOptions = {},
+): AuditLogPort {
+  return {
+    record(entry) {
+      const normalized = normalizeAuditLogEntry(entry);
+      const redacted = options.redact
+        ? options.redact(redactAuditLogEntry(normalized))
+        : redactAuditLogEntry(normalized);
+      return audit.record(redacted);
+    },
+  };
+}
+
+export function createMemoryAuditLog(
+  entries: AuditLogEntry[] = [],
+  options: AuditLogOptions = {},
+): MemoryAuditLogPort {
+  return {
+    entries,
+    record(entry) {
+      const normalized = normalizeAuditLogEntry(entry);
+      entries.push(
+        options.redact
+          ? options.redact(redactAuditLogEntry(normalized))
+          : redactAuditLogEntry(normalized),
+      );
+    },
+  };
+}

package/src/ports/auth.ts

@@ -0,0 +1,76 @@
+export interface AuthRequestLike {
+  headers: Headers;
+  raw?: Request;
+}
+
+export interface AuthSession<User = unknown, Session = unknown> {
+  user: User;
+  session?: Session;
+}
+
+export class AuthUnauthorizedError extends Error {
+  readonly code = "UNAUTHORIZED";
+
+  constructor(message = "Unauthorized") {
+    super(message);
+    this.name = "AuthUnauthorizedError";
+  }
+}
+
+export interface AuthPort<
+  User = unknown,
+  Session = unknown,
+  RequestLike extends AuthRequestLike = AuthRequestLike,
+> {
+  getSession(req: RequestLike): Promise<AuthSession<User, Session> | null>;
+  getUser(req: RequestLike): Promise<User | null>;
+  requireUser(req: RequestLike): Promise<User>;
+}
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type StaticAuthSessionFactory<
+  User,
+  Session,
+  RequestLike extends AuthRequestLike,
+> = (req: RequestLike) => MaybePromise<AuthSession<User, Session> | null>;
+
+export function createStaticAuth<
+  User,
+  Session = unknown,
+  RequestLike extends AuthRequestLike = AuthRequestLike,
+>(
+  session:
+    | AuthSession<User, Session>
+    | null
+    | StaticAuthSessionFactory<User, Session, RequestLike>,
+): AuthPort<User, Session, RequestLike> {
+  async function resolveSession(req: RequestLike) {
+    return typeof session === "function" ? session(req) : session;
+  }
+
+  return {
+    async getSession(req) {
+      return resolveSession(req);
+    },
+    async getUser(req) {
+      return (await resolveSession(req))?.user ?? null;
+    },
+    async requireUser(req) {
+      const user = (await resolveSession(req))?.user ?? null;
+      if (!user) {
+        throw new AuthUnauthorizedError();
+      }
+
+      return user;
+    },
+  };
+}
+
+export function createAnonymousAuth<
+  User = unknown,
+  Session = unknown,
+  RequestLike extends AuthRequestLike = AuthRequestLike,
+>(): AuthPort<User, Session, RequestLike> {
+  return createStaticAuth<User, Session, RequestLike>(null);
+}

package/src/ports/builder.ts

@@ -0,0 +1,97 @@
+/**
+ * PortsBuilder - Mutable builder for composing ports during app initialization
+ *
+ * This builder is a small composition helper for tests and custom bootstrapping
+ * code that wants to assemble ports incrementally.
+ */
+
+/**
+ * A mutable builder around a ports object.
+ * Used during app composition and provider registration.
+ */
+export interface PortsBuilder<Ports> {
+  /**
+   * The current ports object being built.
+   * This is mutated internally when extend/replace are called.
+   */
+  ports: Ports;
+
+  /**
+   * Extend ports with a new key. If the key already exists, it's overwritten.
+   *
+   * Returns the same builder instance with an extended type:
+   *   Ports & { [K in key]: Value }
+   */
+  extend<K extends string, V>(
+    key: K,
+    value: V,
+  ): PortsBuilder<Ports & { [P in K]: V }>;
+
+  /**
+   * Replace an existing key. Does not change the type, but updates the runtime value.
+   * Returns the same builder instance.
+   */
+  replace<K extends keyof Ports>(key: K, value: Ports[K]): PortsBuilder<Ports>;
+}
+
+/**
+ * Create a new PortsBuilder from an initial ports object.
+ *
+ * The builder wraps a mutable object internally and provides type-safe methods
+ * to extend or replace ports. This is used during application composition
+ * helpers that want to modify ports before passing them to a server.
+ *
+ * @example
+ * ```ts
+ * const initialPorts = definePorts({ db: dbAdapter });
+ * const builder = createPortsBuilder(initialPorts);
+ *
+ * // Provider extends with cache
+ * builder.extend("cache", cacheAdapter);
+ *
+ * // Final ports includes both db and cache
+ * const finalPorts = builder.ports;
+ * ```
+ */
+export function createPortsBuilder<Ports>(
+  initialPorts: Ports,
+): PortsBuilder<Ports> {
+  // Keep a mutable object internally
+  // biome-ignore lint/suspicious/noExplicitAny: internal mutable state needs any to accept arbitrary port extensions
+  const state: { ports: any } = {
+    ports: { ...initialPorts },
+  };
+
+  const builder: PortsBuilder<Ports> = {
+    get ports() {
+      // Could freeze in dev, but keep simple
+      return state.ports as Ports;
+    },
+    extend<K extends string, V>(
+      key: K,
+      value: V,
+    ): PortsBuilder<Ports & { [P in K]: V }> {
+      state.ports[key] = value;
+      return builder as unknown as PortsBuilder<Ports & { [P in K]: V }>;
+    },
+    replace<K extends keyof Ports>(
+      key: K,
+      value: Ports[K],
+    ): PortsBuilder<Ports> {
+      state.ports[key] = value;
+      return builder;
+    },
+  };
+
+  return builder;
+}
+
+/**
+ * Extract the Ports type from a PortsBuilder
+ *
+ * @example
+ * ```ts
+ * type MyPorts = PortsOf<typeof builder>;
+ * ```
+ */
+export type PortsOf<PB> = PB extends PortsBuilder<infer P> ? P : never;

package/src/ports/cache.ts

@@ -0,0 +1,94 @@
+export interface CacheSetOptions {
+  /**
+   * Time-to-live in seconds. Omit this for a value that does not expire.
+   */
+  ttlSeconds?: number;
+}
+
+export interface CachePort {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, options?: CacheSetOptions): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  has(key: string): Promise<boolean>;
+  remember(
+    key: string,
+    factory: () => Promise<string>,
+    options?: CacheSetOptions,
+  ): Promise<string>;
+}
+
+type MemoryCacheEntry = {
+  value: string;
+  expiresAt: number | null;
+};
+
+function resolveExpiresAt(options: CacheSetOptions | undefined): number | null {
+  if (options?.ttlSeconds == null) {
+    return null;
+  }
+
+  if (options.ttlSeconds <= 0) {
+    return Date.now();
+  }
+
+  return Date.now() + options.ttlSeconds * 1000;
+}
+
+function isExpired(entry: MemoryCacheEntry): boolean {
+  return entry.expiresAt != null && entry.expiresAt <= Date.now();
+}
+
+export function createMemoryCache(
+  initialValues: Record<string, string> = {},
+): CachePort {
+  const values = new Map<string, MemoryCacheEntry>(
+    Object.entries(initialValues).map(([key, value]) => [
+      key,
+      { value, expiresAt: null },
+    ]),
+  );
+
+  async function getFreshEntry(key: string): Promise<MemoryCacheEntry | null> {
+    const entry = values.get(key);
+    if (!entry) {
+      return null;
+    }
+
+    if (isExpired(entry)) {
+      values.delete(key);
+      return null;
+    }
+
+    return entry;
+  }
+
+  const cache: CachePort = {
+    async get(key) {
+      return (await getFreshEntry(key))?.value ?? null;
+    },
+    async set(key, value, options) {
+      values.set(key, {
+        value,
+        expiresAt: resolveExpiresAt(options),
+      });
+    },
+    async delete(key) {
+      return values.delete(key);
+    },
+    async has(key) {
+      return (await getFreshEntry(key)) != null;
+    },
+    async remember(key, factory, options) {
+      const cached = await cache.get(key);
+      if (cached != null) {
+        return cached;
+      }
+
+      const value = await factory();
+      await cache.set(key, value, options);
+      return value;
+    },
+  };
+
+  return cache;
+}

package/src/ports/clock.ts

@@ -0,0 +1,34 @@
+export interface ClockPort {
+  now(): Date;
+}
+
+export interface FrozenClockPort extends ClockPort {
+  setNow(value: Date | string | number): void;
+  advance(milliseconds: number): void;
+}
+
+function toDate(value: Date | string | number): Date {
+  return value instanceof Date ? new Date(value.getTime()) : new Date(value);
+}
+
+export function createSystemClock(): ClockPort {
+  return {
+    now: () => new Date(),
+  };
+}
+
+export function createFrozenClock(
+  initial: Date | string | number = new Date(0),
+): FrozenClockPort {
+  let current = toDate(initial);
+
+  return {
+    now: () => new Date(current.getTime()),
+    setNow: (value) => {
+      current = toDate(value);
+    },
+    advance: (milliseconds) => {
+      current = new Date(current.getTime() + milliseconds);
+    },
+  };
+}

package/src/ports/events.ts

@@ -0,0 +1,100 @@
+import type {
+  EventPayloadDef,
+  InferEventPayload as InferContractEventPayload,
+  StandardSchema,
+} from "../events";
+import type {
+  JobDef as ContractJobDef,
+  InferJobPayload as InferContractJobPayload,
+} from "../jobs";
+
+/**
+ * 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.
+ */
+export interface DomainEventDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+> extends EventPayloadDef<Name, Payload> {}
+
+/**
+ * Infer the payload type from a DomainEventDef.
+ */
+export type InferEventPayload<E extends DomainEventDef> =
+  InferContractEventPayload<E>;
+
+/**
+ * Represents a job definition with a typed payload schema.
+ *
+ * Job dispatchers use Beignet's first-class job definitions. Inline
+ * dispatchers can run the handler directly;
+ * durable dispatchers can ignore it and enqueue the job name plus parsed
+ * payload.
+ */
+export type JobDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+  Ctx = unknown,
+> = ContractJobDef<Name, Payload, Ctx>;
+
+/**
+ * Infer the payload type from a JobDef.
+ */
+export type InferJobPayload<J extends JobDef> = InferContractJobPayload<J>;
+
+/**
+ * An EventBus port for publishing and subscribing to domain events.
+ *
+ * This interface defines a framework-agnostic contract for event-driven
+ * communication within your application.
+ *
+ * @example
+ * ```ts
+ * import { createInMemoryEventBus } from "@beignet/provider-event-bus-memory";
+ *
+ * const eventBus = createInMemoryEventBus();
+ *
+ * // Subscribe to an event
+ * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+ *   console.log(`User registered: ${payload.email}`);
+ * });
+ *
+ * // Publish an event
+ * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
+ *
+ * // Unsubscribe when done
+ * unsubscribe();
+ * ```
+ */
+export interface EventBusPort {
+  /**
+   * Publish a domain event with a typed payload.
+   */
+  publish<E extends DomainEventDef>(
+    event: E,
+    payload: InferEventPayload<E>,
+  ): Promise<void> | void;
+
+  /**
+   * Subscribe to a domain event. Returns an unsubscribe function.
+   */
+  subscribe<E extends DomainEventDef>(
+    event: E,
+    handler: (payload: InferEventPayload<E>) => Promise<void> | void,
+  ): () => void;
+}
+
+/**
+ * A port for dispatching explicit background jobs.
+ *
+ * Jobs represent work to do, not facts that happened. Implementations may run
+ * inline in tests, enqueue into a durable worker, or call an external job
+ * system.
+ */
+export interface JobDispatcherPort {
+  dispatch<J extends JobDef>(
+    job: J,
+    payload: InferJobPayload<J>,
+  ): Promise<void> | void;
+}