@beignet/core 0.0.1 → 0.0.2

package/src/pagination/index.ts

@@ -0,0 +1,278 @@
+/**
+ * Sort direction for list queries.
+ */
+export type SortDirection = "asc" | "desc";
+
+/**
+ * Sort option for a whitelisted field.
+ */
+export type SortOption<Field extends string = string> = {
+  /**
+   * Field to sort by.
+   */
+  field: Field;
+  /**
+   * Sort direction.
+   */
+  direction: SortDirection;
+};
+
+/**
+ * Normalized offset pagination request.
+ */
+export interface OffsetPage {
+  /**
+   * Pagination mode.
+   */
+  readonly kind: "offset";
+  /**
+   * Page size after defaulting and max-limit clamping.
+   */
+  readonly limit: number;
+  /**
+   * Zero-based item offset.
+   */
+  readonly offset: number;
+}
+
+/**
+ * Normalized cursor pagination request.
+ */
+export interface CursorPage {
+  /**
+   * Pagination mode.
+   */
+  readonly kind: "cursor";
+  /**
+   * Page size after defaulting and max-limit clamping.
+   */
+  readonly limit: number;
+  /**
+   * Cursor for the current page, or null for the first page.
+   */
+  readonly cursor: string | null;
+}
+
+/**
+ * Normalized pagination request.
+ */
+export type Page = OffsetPage | CursorPage;
+
+/**
+ * Offset pagination response metadata.
+ */
+export type OffsetPageInfo = OffsetPage & {
+  /**
+   * Total item count.
+   */
+  readonly total: number;
+  /**
+   * Whether another page exists.
+   */
+  readonly hasMore: boolean;
+};
+
+/**
+ * Cursor pagination response metadata.
+ */
+export type CursorPageInfo = CursorPage & {
+  /**
+   * Cursor for the next page, or null when there is no next page.
+   */
+  readonly nextCursor: string | null;
+  /**
+   * Whether another page exists.
+   */
+  readonly hasMore: boolean;
+};
+
+/**
+ * Pagination response metadata.
+ */
+export type PageInfo = OffsetPageInfo | CursorPageInfo;
+
+/**
+ * Paginated list result.
+ */
+export interface PageResult<TItem, TPage extends PageInfo = PageInfo> {
+  /**
+   * Page items. Result helpers clone the input array.
+   */
+  readonly items: TItem[];
+  /**
+   * Page metadata.
+   */
+  readonly page: TPage;
+}
+
+/**
+ * Options for normalizing pagination input.
+ */
+export interface NormalizePageOptions {
+  /**
+   * Limit used when the caller does not provide one.
+   */
+  readonly defaultLimit: number;
+  /**
+   * Maximum allowed limit. Larger caller values are clamped.
+   */
+  readonly maxLimit: number;
+}
+
+/**
+ * Raw offset pagination input.
+ */
+export interface OffsetPageInput {
+  /**
+   * Requested page size.
+   */
+  readonly limit?: number | null;
+  /**
+   * Requested zero-based offset.
+   */
+  readonly offset?: number | null;
+}
+
+/**
+ * Raw cursor pagination input.
+ */
+export interface CursorPageInput {
+  /**
+   * Requested page size.
+   */
+  readonly limit?: number | null;
+  /**
+   * Requested cursor.
+   */
+  readonly cursor?: string | null;
+}
+
+/**
+ * Error thrown when pagination input is invalid.
+ */
+export class PaginationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PaginationError";
+  }
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new PaginationError(`${name} must be a positive integer.`);
+  }
+}
+
+function normalizeLimit(
+  input: number | null | undefined,
+  options: NormalizePageOptions,
+): number {
+  assertPositiveInteger("defaultLimit", options.defaultLimit);
+  assertPositiveInteger("maxLimit", options.maxLimit);
+
+  if (options.defaultLimit > options.maxLimit) {
+    throw new PaginationError(
+      "defaultLimit must be less than or equal to maxLimit.",
+    );
+  }
+
+  if (input == null) return options.defaultLimit;
+
+  if (!Number.isInteger(input) || input < 1) {
+    throw new PaginationError("limit must be a positive integer.");
+  }
+
+  return Math.min(input, options.maxLimit);
+}
+
+/**
+ * Normalize offset pagination input.
+ *
+ * The limit is defaulted and clamped to `maxLimit`; offset must be a
+ * non-negative integer.
+ */
+export function normalizeOffsetPage(
+  input: OffsetPageInput,
+  options: NormalizePageOptions,
+): OffsetPage {
+  const limit = normalizeLimit(input.limit, options);
+  const offset = input.offset ?? 0;
+
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new PaginationError("offset must be a non-negative integer.");
+  }
+
+  return {
+    kind: "offset",
+    limit,
+    offset,
+  };
+}
+
+/**
+ * Normalize cursor pagination input.
+ *
+ * The limit is defaulted and clamped to `maxLimit`; cursor must be a string or
+ * null.
+ */
+export function normalizeCursorPage(
+  input: CursorPageInput,
+  options: NormalizePageOptions,
+): CursorPage {
+  const limit = normalizeLimit(input.limit, options);
+  const cursor = input.cursor ?? null;
+
+  if (cursor !== null && typeof cursor !== "string") {
+    throw new PaginationError("cursor must be a string or null.");
+  }
+
+  return {
+    kind: "cursor",
+    limit,
+    cursor,
+  };
+}
+
+/**
+ * Create an offset page result and derive `hasMore`.
+ */
+export function offsetPageResult<TItem>(
+  items: readonly TItem[],
+  page: OffsetPage,
+  total: number,
+): PageResult<TItem, OffsetPageInfo> {
+  if (!Number.isInteger(total) || total < 0) {
+    throw new PaginationError("total must be a non-negative integer.");
+  }
+
+  return {
+    items: [...items],
+    page: {
+      ...page,
+      total,
+      hasMore: page.offset + items.length < total,
+    },
+  };
+}
+
+/**
+ * Create a cursor page result and derive `hasMore` from `nextCursor`.
+ */
+export function cursorPageResult<TItem>(
+  items: readonly TItem[],
+  page: CursorPage,
+  nextCursor: string | null,
+): PageResult<TItem, CursorPageInfo> {
+  if (nextCursor !== null && typeof nextCursor !== "string") {
+    throw new PaginationError("nextCursor must be a string or null.");
+  }
+
+  return {
+    items: [...items],
+    page: {
+      ...page,
+      nextCursor,
+      hasMore: nextCursor !== null,
+    },
+  };
+}

package/src/ports/audit.ts

@@ -1,9 +1,26 @@
 import { redactValue } from "./redaction";
 
+/**
+ * The normalized category of actor that caused application activity.
+ *
+ * Actors describe who or what performed work for request context,
+ * authorization, audit logs, and diagnostics. They do not authenticate the
+ * request by themselves.
+ */
 export type ActivityActorType = "anonymous" | "service" | "system" | "user";
 
+/**
+ * Whether an audited activity completed successfully or intentionally records
+ * a failed attempt.
+ */
 export type AuditOutcome = "success" | "failure";
 
+/**
+ * JSON-like metadata values accepted by activity and audit descriptors.
+ *
+ * Metadata should stay intentionally small. Prefer stable IDs and short labels
+ * over full request bodies, secrets, PHI, or PII.
+ */
 export type ActivityMetadataValue =
   | ActivityMetadataValue[]
   | boolean
@@ -12,44 +29,146 @@ export type ActivityMetadataValue =
   | string
   | { [key: string]: ActivityMetadataValue | undefined };
 
+/**
+ * Additional structured metadata attached to actors, tenants, resources, or
+ * audit entries.
+ */
 export type ActivityMetadata = Record<
   string,
   ActivityMetadataValue | undefined
 >;
 
+/**
+ * A normalized descriptor for the person, service, or system process that
+ * caused application activity.
+ *
+ * Store this on application context as `ctx.actor` so routes, use cases, jobs,
+ * policies, audit logs, and devtools share one identity shape.
+ */
 export interface ActivityActor {
+  /**
+   * The actor category.
+   */
   type: ActivityActorType;
+  /**
+   * Stable application ID for this actor, when known.
+   */
   id?: string;
+  /**
+   * Human-readable label for diagnostics and audit views.
+   */
   displayName?: string;
+  /**
+   * Small, redaction-safe metadata about the actor.
+   */
   metadata?: ActivityMetadata;
 }
 
+/**
+ * A normalized tenant/account/workspace scope for activity.
+ *
+ * This is a context value used by audit logs, authorization, and diagnostics.
+ * It does not create, load, or persist a tenant record.
+ */
 export interface ActivityTenant {
+  /**
+   * Stable tenant/account/workspace ID.
+   */
   id: string;
+  /**
+   * Optional human-readable tenant slug.
+   */
   slug?: string;
+  /**
+   * Small, redaction-safe metadata about the tenant.
+   */
   metadata?: ActivityMetadata;
 }
 
+/**
+ * A normalized descriptor for the business object affected by an audit entry.
+ */
 export interface ActivityResource {
+  /**
+   * Resource type, usually a singular domain noun such as "post", "invoice",
+   * or "appointment".
+   */
   type: string;
+  /**
+   * Stable resource ID, when known.
+   */
   id?: string;
+  /**
+   * Human-readable resource label for audit views.
+   */
   name?: string;
+  /**
+   * Small, redaction-safe metadata about the resource.
+   */
   metadata?: ActivityMetadata;
 }
 
+/**
+ * A normalized audit/activity log entry.
+ *
+ * Application code usually creates these through an app-owned helper such as
+ * `auditEntry(ctx, { action, resource })` so actor, tenant, request ID, and
+ * trace ID are copied from context consistently. Durability depends on the
+ * `AuditLogPort` implementation.
+ */
 export interface AuditLogEntry {
+  /**
+   * Stable action name, usually namespaced by feature and workflow.
+   *
+   * @example "posts.publish"
+   */
   action: string;
+  /**
+   * Actor that caused the activity.
+   */
   actor: ActivityActor;
+  /**
+   * Timestamp assigned when the activity occurred.
+   */
   occurredAt: Date;
+  /**
+   * Whether the activity succeeded or records a failed attempt.
+   */
   outcome: AuditOutcome;
+  /**
+   * Small, redaction-safe metadata about the activity.
+   */
   metadata?: ActivityMetadata;
+  /**
+   * Optional human-readable audit message.
+   */
   message?: string;
+  /**
+   * Request correlation ID, when the activity originated from a request or
+   * background context.
+   */
   requestId?: string;
+  /**
+   * Business resource affected by the activity.
+   */
   resource?: ActivityResource;
+  /**
+   * Tenant/account/workspace scope for the activity.
+   */
   tenant?: ActivityTenant;
+  /**
+   * Trace correlation ID, when tracing is enabled.
+   */
   traceId?: string;
 }
 
+/**
+ * Input accepted by `AuditLogPort.record(...)`.
+ *
+ * `occurredAt` and `outcome` are optional at call sites. Adapters that store
+ * audit entries should call `normalizeAuditLogEntry(...)` before persistence or
+ * otherwise apply equivalent defaults.
+ */
 export type AuditLogEntryInput = Omit<
   AuditLogEntry,
   "occurredAt" | "outcome"
@@ -58,24 +177,78 @@ export type AuditLogEntryInput = Omit<
   outcome?: AuditOutcome;
 };
 
+/**
+ * App-facing port for audit/activity logging.
+ *
+ * Production implementations should usually write to a durable database table,
+ * append-only log, or external audit service. Tests can use an in-memory
+ * adapter. Application code should depend on this interface, not on a concrete
+ * audit provider.
+ */
 export interface AuditLogPort {
+  /**
+   * Persist or capture an audit entry.
+   */
   record(entry: AuditLogEntryInput): Promise<void> | void;
 }
 
+/**
+ * In-memory audit log port used by tests and local examples.
+ */
 export interface MemoryAuditLogPort extends AuditLogPort {
+  /**
+   * Captured, normalized, redacted audit entries.
+   */
   entries: AuditLogEntry[];
 }
 
+/**
+ * Options shared by audit log wrappers and in-memory audit adapters.
+ */
 export interface AuditLogOptions {
+  /**
+   * Optional final redaction/customization step applied after Beignet's default
+   * metadata redaction.
+   */
   redact?: (entry: AuditLogEntry) => AuditLogEntry;
 }
 
+/**
+ * Create an anonymous actor descriptor for unauthenticated activity.
+ *
+ * This helper only creates a normalized context value. It does not perform
+ * authentication.
+ *
+ * @example
+ * ```ts
+ * const actor = createAnonymousActor();
+ * ```
+ *
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "anonymous"`.
+ */
 export function createAnonymousActor(
   options: Omit<ActivityActor, "type"> = {},
 ): ActivityActor {
   return { type: "anonymous", ...options };
 }
 
+/**
+ * Create a service actor descriptor for work initiated by another service or
+ * integration.
+ *
+ * This is useful for webhooks, internal service calls, or integration-driven
+ * background jobs.
+ *
+ * @example
+ * ```ts
+ * const actor = createServiceActor("stripe-webhook");
+ * ```
+ *
+ * @param id - Stable service or integration ID.
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "service"`.
+ */
 export function createServiceActor(
   id: string,
   options: Omit<ActivityActor, "type" | "id"> = {},
@@ -83,6 +256,21 @@ export function createServiceActor(
   return { type: "service", id, ...options };
 }
 
+/**
+ * Create a system actor descriptor for framework or app-owned background work.
+ *
+ * Use this for scheduled tasks, scripts, maintenance jobs, and other work that
+ * is not directly caused by a user or external service.
+ *
+ * @example
+ * ```ts
+ * const actor = createSystemActor("nightly-maintenance");
+ * ```
+ *
+ * @param id - Stable system actor ID. Defaults to `"system"`.
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "system"`.
+ */
 export function createSystemActor(
   id = "system",
   options: Omit<ActivityActor, "type" | "id"> = {},
@@ -90,6 +278,25 @@ export function createSystemActor(
   return { type: "system", id, ...options };
 }
 
+/**
+ * Create a user actor descriptor for authenticated user activity.
+ *
+ * This helper only normalizes a known user ID for context, authorization,
+ * audit, and diagnostics. It does not verify a session or load a user record.
+ * Resolve authentication first, then call this helper with the authenticated
+ * user ID.
+ *
+ * @example
+ * ```ts
+ * const actor = createUserActor(session.user.id, {
+ *   displayName: session.user.name,
+ * });
+ * ```
+ *
+ * @param id - Stable application user ID.
+ * @param options - Optional display name or metadata to include.
+ * @returns An activity actor with `type: "user"`.
+ */
 export function createUserActor(
   id: string,
   options: Omit<ActivityActor, "type" | "id"> = {},
@@ -97,6 +304,25 @@ export function createUserActor(
   return { type: "user", id, ...options };
 }
 
+/**
+ * Create a tenant/account/workspace descriptor for request or background
+ * context.
+ *
+ * This helper only creates a normalized context value used by audit,
+ * authorization, logs, and diagnostics. It does not create, load, or persist a
+ * tenant record.
+ *
+ * @example
+ * ```ts
+ * const tenant = createTenant(session.organizationId, {
+ *   slug: session.organizationSlug,
+ * });
+ * ```
+ *
+ * @param id - Stable tenant/account/workspace ID.
+ * @param options - Optional slug or metadata to include.
+ * @returns A normalized activity tenant descriptor.
+ */
 export function createTenant(
   id: string,
   options: Omit<ActivityTenant, "id"> = {},
@@ -104,6 +330,12 @@ export function createTenant(
   return { id, ...options };
 }
 
+/**
+ * Fill default audit fields for an input entry.
+ *
+ * @param entry - Partial audit entry accepted by `AuditLogPort.record(...)`.
+ * @returns A complete audit entry with `occurredAt` and `outcome` populated.
+ */
 export function normalizeAuditLogEntry(
   entry: AuditLogEntryInput,
 ): AuditLogEntry {
@@ -114,6 +346,15 @@ export function normalizeAuditLogEntry(
   };
 }
 
+/**
+ * Redact metadata on an already-normalized audit entry.
+ *
+ * This redacts metadata values on the entry, actor, tenant, and resource using
+ * the default redaction rules from `redactValue(...)`.
+ *
+ * @param entry - Audit entry to redact.
+ * @returns A shallow copy with redacted metadata fields.
+ */
 export function redactAuditLogEntry(entry: AuditLogEntry): AuditLogEntry {
   return {
     ...entry,
@@ -143,6 +384,16 @@ export function redactAuditLogEntry(entry: AuditLogEntry): AuditLogEntry {
   };
 }
 
+/**
+ * Wrap an audit log port with default audit metadata redaction.
+ *
+ * Use this around durable adapters so application code can record entries
+ * without each call site remembering to redact metadata.
+ *
+ * @param audit - Underlying audit log port to write to after redaction.
+ * @param options - Optional final redaction/customization hook.
+ * @returns An audit log port that normalizes and redacts before writing.
+ */
 export function createRedactedAuditLog(
   audit: AuditLogPort,
   options: AuditLogOptions = {},
@@ -158,6 +409,26 @@ export function createRedactedAuditLog(
   };
 }
 
+/**
+ * Create an in-memory audit log for tests and local examples.
+ *
+ * Entries are normalized and redacted before being pushed into the shared
+ * `entries` array.
+ *
+ * @example
+ * ```ts
+ * const audit = createMemoryAuditLog();
+ * await audit.record({
+ *   action: "posts.publish",
+ *   actor: createUserActor("user_1"),
+ * });
+ * expect(audit.entries).toHaveLength(1);
+ * ```
+ *
+ * @param entries - Optional backing array, useful when tests need shared state.
+ * @param options - Optional final redaction/customization hook.
+ * @returns An in-memory audit log port with captured `entries`.
+ */
 export function createMemoryAuditLog(
   entries: AuditLogEntry[] = [],
   options: AuditLogOptions = {},