@beignet/core 0.0.1 → 0.0.2

package/src/ports/auth.ts

@@ -1,13 +1,37 @@
+/**
+ * Minimal request shape consumed by Beignet auth ports.
+ *
+ * Framework adapters can pass richer request objects, but auth providers should
+ * only rely on headers and the optional raw platform request unless they
+ * declare a more specific `RequestLike` type.
+ */
 export interface AuthRequestLike {
+  /**
+   * Request headers used for cookies, bearer tokens, API keys, or provider
+   * specific auth data.
+   */
   headers: Headers;
+  /**
+   * Raw platform request, when the runtime has one available.
+   */
   raw?: Request;
 }
 
+/**
+ * Normalized authenticated session returned by an `AuthPort`.
+ *
+ * `user` is the app/provider user object. `session` can carry provider-specific
+ * session state such as cookie session metadata or token claims.
+ */
 export interface AuthSession<User = unknown, Session = unknown> {
   user: User;
   session?: Session;
 }
 
+/**
+ * Error thrown by auth helpers when a route or workflow requires a user but no
+ * authenticated user is available.
+ */
 export class AuthUnauthorizedError extends Error {
   readonly code = "UNAUTHORIZED";
 
@@ -17,24 +41,61 @@ export class AuthUnauthorizedError extends Error {
   }
 }
 
+/**
+ * App-facing authentication port.
+ *
+ * Implement this with a provider adapter such as Better Auth, a custom session
+ * lookup, or a test fake. The port identifies the current user; it does not
+ * decide whether that user may perform a business action. Keep authorization in
+ * policies or use cases.
+ */
 export interface AuthPort<
   User = unknown,
   Session = unknown,
   RequestLike extends AuthRequestLike = AuthRequestLike,
 > {
+  /**
+   * Return the current session, or `null` when the request is unauthenticated.
+   */
   getSession(req: RequestLike): Promise<AuthSession<User, Session> | null>;
+  /**
+   * Return the current user, or `null` when unauthenticated.
+   */
   getUser(req: RequestLike): Promise<User | null>;
+  /**
+   * Return the current user or throw `AuthUnauthorizedError`.
+   */
   requireUser(req: RequestLike): Promise<User>;
 }
 
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Request-aware factory for a static auth session.
+ */
 export type StaticAuthSessionFactory<
   User,
   Session,
   RequestLike extends AuthRequestLike,
 > = (req: RequestLike) => MaybePromise<AuthSession<User, Session> | null>;
 
+/**
+ * Create an auth port from a fixed session or request-aware session factory.
+ *
+ * This is useful for tests, examples, and simple apps. Production apps usually
+ * use a provider-backed auth port that verifies cookies, tokens, or sessions.
+ *
+ * @example
+ * ```ts
+ * const auth = createStaticAuth({
+ *   user: { id: "user_1", name: "Ada" },
+ * });
+ * ```
+ *
+ * @param session - Fixed session, `null`, or a function that resolves a session
+ * from the request.
+ * @returns An `AuthPort` implementation backed by the provided session source.
+ */
 export function createStaticAuth<
   User,
   Session = unknown,
@@ -67,6 +128,15 @@ export function createStaticAuth<
   };
 }
 
+/**
+ * Create an auth port that always treats requests as unauthenticated.
+ *
+ * Use this in tests or examples where auth is intentionally absent. It is not a
+ * security boundary; it simply returns `null` from `getSession`/`getUser` and
+ * throws from `requireUser`.
+ *
+ * @returns An `AuthPort` with no active session.
+ */
 export function createAnonymousAuth<
   User = unknown,
   Session = unknown,

package/src/ports/cache.ts

@@ -1,3 +1,6 @@
+/**
+ * Options for storing a cache value.
+ */
 export interface CacheSetOptions {
   /**
    * Time-to-live in seconds. Omit this for a value that does not expire.
@@ -5,11 +8,39 @@ export interface CacheSetOptions {
   ttlSeconds?: number;
 }
 
+/**
+ * App-facing string cache port.
+ *
+ * Values are intentionally strings so adapters can map cleanly to Redis,
+ * Upstash, and other key/value stores. Serialize structured values at the app
+ * boundary.
+ */
 export interface CachePort {
+  /**
+   * Return a fresh value for `key`, or `null` when missing or expired.
+   */
   get(key: string): Promise<string | null>;
+  /**
+   * Store a string value.
+   */
   set(key: string, value: string, options?: CacheSetOptions): Promise<void>;
+  /**
+   * Delete a cache key.
+   *
+   * @returns `true` when the key existed.
+   */
   delete(key: string): Promise<boolean>;
+  /**
+   * Return whether a fresh value exists for `key`.
+   */
   has(key: string): Promise<boolean>;
+  /**
+   * Return a cached value or compute, store, and return a new value.
+   *
+   * Implementations are not required to provide single-flight behavior. If
+   * concurrent cache fills matter, choose an adapter that documents that
+   * guarantee or protect the factory at the application layer.
+   */
   remember(
     key: string,
     factory: () => Promise<string>,
@@ -38,6 +69,16 @@ function isExpired(entry: MemoryCacheEntry): boolean {
   return entry.expiresAt != null && entry.expiresAt <= Date.now();
 }
 
+/**
+ * Create an in-memory cache for tests, examples, and single-process
+ * development.
+ *
+ * This adapter is not durable or distributed. Values are lost when the process
+ * exits and are not shared across workers, regions, or serverless invocations.
+ *
+ * @param initialValues - Optional initial string values without TTL.
+ * @returns A cache port backed by a local `Map`.
+ */
 export function createMemoryCache(
   initialValues: Record<string, string> = {},
 ): CachePort {

package/src/ports/clock.ts

@@ -1,9 +1,27 @@
+/**
+ * App-facing time source.
+ *
+ * Use this port anywhere deterministic time matters, such as use-case tests,
+ * scheduled work, idempotency windows, or audit timestamps.
+ */
 export interface ClockPort {
+  /**
+   * Return the current time according to this clock.
+   */
   now(): Date;
 }
 
+/**
+ * Mutable clock implementation used by tests.
+ */
 export interface FrozenClockPort extends ClockPort {
+  /**
+   * Replace the current time.
+   */
   setNow(value: Date | string | number): void;
+  /**
+   * Move the current time forward by the given number of milliseconds.
+   */
   advance(milliseconds: number): void;
 }
 
@@ -11,12 +29,32 @@ function toDate(value: Date | string | number): Date {
   return value instanceof Date ? new Date(value.getTime()) : new Date(value);
 }
 
+/**
+ * Create a clock backed by `new Date()`.
+ *
+ * Use this as the default production `ClockPort` when the app does not need a
+ * provider-specific time source.
+ *
+ * @returns A clock that reads the current system time.
+ */
 export function createSystemClock(): ClockPort {
   return {
     now: () => new Date(),
   };
 }
 
+/**
+ * Create a mutable clock for deterministic tests.
+ *
+ * @example
+ * ```ts
+ * const clock = createFrozenClock("2026-01-01T00:00:00.000Z");
+ * clock.advance(1000);
+ * ```
+ *
+ * @param initial - Initial time for the clock. Defaults to Unix epoch.
+ * @returns A clock whose time can be replaced or advanced.
+ */
 export function createFrozenClock(
   initial: Date | string | number = new Date(0),
 ): FrozenClockPort {

package/src/ports/id-generator.ts

@@ -1,11 +1,35 @@
+/**
+ * App-facing ID generation port.
+ *
+ * Use this when deterministic IDs matter in use-case tests or when production
+ * infrastructure owns ID generation.
+ */
 export interface IdGeneratorPort {
+  /**
+   * Return the next ID.
+   */
   nextId(): string;
 }
 
+/**
+ * Mutable sequential ID generator used by tests and simple examples.
+ */
 export interface SequenceIdGeneratorPort extends IdGeneratorPort {
+  /**
+   * Reset the next sequence value.
+   */
   reset(next?: number): void;
 }
 
+/**
+ * Create an ID generator backed by `globalThis.crypto.randomUUID()`.
+ *
+ * The factory itself does not read from `crypto`; the returned generator's
+ * `nextId()` method throws if the current runtime does not expose
+ * `globalThis.crypto.randomUUID()`.
+ *
+ * @returns An ID generator that returns UUID strings from `nextId()`.
+ */
 export function createUuidIdGenerator(): IdGeneratorPort {
   return {
     nextId: () => {
@@ -20,6 +44,19 @@ export function createUuidIdGenerator(): IdGeneratorPort {
   };
 }
 
+/**
+ * Create a deterministic sequence ID generator for tests and examples.
+ *
+ * @example
+ * ```ts
+ * const ids = createSequenceIdGenerator({ prefix: "post", start: 10 });
+ * ids.nextId(); // "post_10"
+ * ids.nextId(); // "post_11"
+ * ```
+ *
+ * @param options - Optional ID prefix and starting sequence number.
+ * @returns A mutable sequence ID generator.
+ */
 export function createSequenceIdGenerator(
   options: { prefix?: string; start?: number } = {},
 ): SequenceIdGeneratorPort {

package/src/ports/index.ts

@@ -10,6 +10,8 @@
  * - `EventBusPort` – interface for event bus implementations
  * - `JobDispatcherPort` – interface for job dispatch implementations
  * - `UnitOfWorkPort` – interface for app-owned transaction boundaries
+ * - `OutboxPort` – interface for durable event/job delivery storage
+ * - `IdempotencyPort` – interface for retry-safe command/key storage
  * - `AuthPort` – interface for request authentication implementations
  * - `AuditLogPort` – interface for audit/activity log implementations
  * - `ClockPort` – interface for deterministic time
@@ -21,7 +23,10 @@
  * - `StoragePort` – interface for object/file storage implementations
  *
  * Dedicated framework areas own their capability-specific APIs:
+ * - `@beignet/core/idempotency` owns idempotency helpers and test adapters
  * - `@beignet/core/mail` owns `MailerPort` and mail test adapters
+ * - `@beignet/core/notifications` owns notification helpers and test adapters
+ * - `@beignet/core/outbox` owns durable outbox helpers and test adapters
  * - `@beignet/core/schedules` owns scheduled task definitions and runners
  */
 
@@ -79,6 +84,44 @@ export interface PortsContext<P extends AnyPorts = AnyPorts> {
   ports: P;
 }
 
+/**
+ * Idempotency port exports.
+ */
+export type {
+  IdempotencyCompleteInput,
+  IdempotencyFailInput,
+  IdempotencyPort,
+  IdempotencyReservation,
+  IdempotencyReserveInput,
+} from "../idempotency";
+/**
+ * Notification port exports.
+ */
+export type {
+  MemoryNotificationDelivery,
+  MemoryNotificationPort,
+  NotificationChannelResult,
+  NotificationPort,
+  SendNotificationOptions,
+  SendNotificationResult,
+} from "../notifications";
+/**
+ * Transactional outbox port exports.
+ */
+export type {
+  ClaimedOutboxMessage,
+  OutboxClaimBatchOptions,
+  OutboxEnqueueInput,
+  OutboxMarkDeliveredInput,
+  OutboxMarkFailedInput,
+  OutboxMessage,
+  OutboxMessageKind,
+  OutboxMessageStatus,
+  OutboxPort,
+} from "../outbox";
+/**
+ * Audit log port exports.
+ */
 export type {
   ActivityActor,
   ActivityActorType,
@@ -93,6 +136,9 @@ export type {
   AuditOutcome,
   MemoryAuditLogPort,
 } from "./audit";
+/**
+ * Audit log helper exports.
+ */
 export {
   createAnonymousActor,
   createMemoryAuditLog,
@@ -104,30 +150,50 @@ export {
   normalizeAuditLogEntry,
   redactAuditLogEntry,
 } from "./audit";
+/**
+ * Auth port exports.
+ */
 export type {
   AuthPort,
   AuthRequestLike,
   AuthSession,
   StaticAuthSessionFactory,
 } from "./auth";
+/**
+ * Auth helper exports.
+ */
 export {
   AuthUnauthorizedError,
   createAnonymousAuth,
   createStaticAuth,
 } from "./auth";
-// Ports builder exports
+/**
+ * Ports builder exports.
+ */
 export {
   createPortsBuilder,
   type PortsBuilder,
   type PortsOf,
 } from "./builder";
+/**
+ * Cache port exports.
+ */
 export type { CachePort, CacheSetOptions } from "./cache";
-// Cache port exports
+/**
+ * Cache helper exports.
+ */
 export { createMemoryCache } from "./cache";
-// Clock port exports
+/**
+ * Clock port exports.
+ */
 export type { ClockPort, FrozenClockPort } from "./clock";
+/**
+ * Clock helper exports.
+ */
 export { createFrozenClock, createSystemClock } from "./clock";
-// Event bus exports
+/**
+ * Event bus and job dispatcher port exports.
+ */
 export type {
   DomainEventDef,
   EventBusPort,
@@ -136,21 +202,33 @@ export type {
   JobDef,
   JobDispatcherPort,
 } from "./events";
-// Id generator port exports
+/**
+ * ID generator port exports.
+ */
 export type { IdGeneratorPort, SequenceIdGeneratorPort } from "./id-generator";
+/**
+ * ID generator helper exports.
+ */
 export {
   createSequenceIdGenerator,
   createUuidIdGenerator,
 } from "./id-generator";
-// Logger port exports
+/**
+ * Logger port exports.
+ */
 export type {
   LoggerPort,
   LogLevel,
   MemoryLogEntry,
   MemoryLoggerPort,
 } from "./logger";
+/**
+ * Logger helper exports.
+ */
 export { createMemoryLogger, createNoopLogger } from "./logger";
-// Policy and authorization gate exports
+/**
+ * Policy and authorization gate type exports.
+ */
 export type {
   BoundGate,
   CreateGateOptions,
@@ -166,6 +244,9 @@ export type {
   PolicyResolver,
   PolicySubjectArgs,
 } from "./policy";
+/**
+ * Policy and authorization gate helper exports.
+ */
 export {
   allow,
   createGate,
@@ -173,14 +254,21 @@ export {
   deny,
   GateAuthorizationError,
 } from "./policy";
+/**
+ * Rate limit port exports.
+ */
 export type {
   RateLimitHitOptions,
   RateLimitPort,
   RateLimitResult,
 } from "./rate-limit";
-// Rate limit port exports
+/**
+ * Rate limit helper exports.
+ */
 export { createMemoryRateLimiter } from "./rate-limit";
-// Redaction exports
+/**
+ * Redaction helper exports.
+ */
 export {
   createRedactor,
   DEFAULT_CIRCULAR_VALUE,
@@ -196,7 +284,9 @@ export {
   redactHeaders,
   redactValue,
 } from "./redaction";
-// Storage port exports
+/**
+ * Storage port exports.
+ */
 export type {
   MemoryStorageOptions,
   StorageBody,
@@ -207,8 +297,13 @@ export type {
   StoragePutOptions,
   StorageVisibility,
 } from "./storage";
+/**
+ * Storage helper exports.
+ */
 export { createMemoryStorage } from "./storage";
-// Unit of Work exports
+/**
+ * Unit of Work port exports.
+ */
 export {
   type BufferedDomainEventRecorder,
   createDomainEventRecorder,

package/src/ports/logger.ts

@@ -1,15 +1,48 @@
+/**
+ * Supported structured logger levels.
+ */
 export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
 
+/**
+ * App-facing structured logger port.
+ *
+ * Application code logs through this interface so production can use Pino,
+ * Datadog, or another adapter while tests can use no-op or memory loggers.
+ */
 export interface LoggerPort {
+  /**
+   * Log very detailed diagnostic information.
+   */
   trace(message: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log debug-level diagnostic information.
+   */
   debug(message: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log normal application progress.
+   */
   info(message: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log recoverable problems or unusual conditions.
+   */
   warn(message: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log failed operations.
+   */
   error(message: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log unrecoverable failures.
+   */
   fatal(message: string, meta?: Record<string, unknown>): void;
+  /**
+   * Return a logger with additional structured bindings.
+   */
   child(bindings: Record<string, unknown>): LoggerPort;
 }
 
+/**
+ * Captured entry from `createMemoryLogger(...)`.
+ */
 export interface MemoryLogEntry {
   level: LogLevel;
   message: string;
@@ -17,10 +50,23 @@ export interface MemoryLogEntry {
   bindings: Record<string, unknown>;
 }
 
+/**
+ * In-memory logger port used by tests and local assertions.
+ */
 export interface MemoryLoggerPort extends LoggerPort {
+  /**
+   * Captured log entries in call order.
+   */
   entries: MemoryLogEntry[];
 }
 
+/**
+ * Create a logger that discards every log call.
+ *
+ * Use this in tests where logging is irrelevant.
+ *
+ * @returns A logger port whose methods are no-ops.
+ */
 export function createNoopLogger(): LoggerPort {
   const logger: LoggerPort = {
     trace: () => {},
@@ -35,6 +81,16 @@ export function createNoopLogger(): LoggerPort {
   return logger;
 }
 
+/**
+ * Create a logger that captures entries in memory.
+ *
+ * Child loggers inherit existing bindings and append new bindings to each
+ * captured entry.
+ *
+ * @param bindings - Structured bindings attached to every captured entry.
+ * @param entries - Optional shared entry array.
+ * @returns A logger port with an inspectable `entries` array.
+ */
 export function createMemoryLogger(
   bindings: Record<string, unknown> = {},
   entries: MemoryLogEntry[] = [],