@beignet/core 0.0.1 → 0.0.3

package/dist/pagination/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 declare class PaginationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Normalize offset pagination input.
+ *
+ * The limit is defaulted and clamped to `maxLimit`; offset must be a
+ * non-negative integer.
+ */
+export declare function normalizeOffsetPage(input: OffsetPageInput, options: NormalizePageOptions): OffsetPage;
+/**
+ * Normalize cursor pagination input.
+ *
+ * The limit is defaulted and clamped to `maxLimit`; cursor must be a string or
+ * null.
+ */
+export declare function normalizeCursorPage(input: CursorPageInput, options: NormalizePageOptions): CursorPage;
+/**
+ * Create an offset page result and derive `hasMore`.
+ */
+export declare function offsetPageResult<TItem>(items: readonly TItem[], page: OffsetPage, total: number): PageResult<TItem, OffsetPageInfo>;
+/**
+ * Create a cursor page result and derive `hasMore` from `nextCursor`.
+ */
+export declare function cursorPageResult<TItem>(items: readonly TItem[], page: CursorPage, nextCursor: string | null): PageResult<TItem, CursorPageInfo>;
+//# sourceMappingURL=index.d.ts.map

package/dist/pagination/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pagination/index.ts"],"names":[],"mappings":"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"}

package/dist/pagination/index.js

@@ -0,0 +1,96 @@
+/**
+ * Error thrown when pagination input is invalid.
+ */
+export class PaginationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaginationError";
+    }
+}
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new PaginationError(`${name} must be a positive integer.`);
+    }
+}
+function normalizeLimit(input, options) {
+    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, options) {
+    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, options) {
+    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(items, page, total) {
+    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(items, page, nextCursor) {
+    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,
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/pagination/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pagination/index.ts"],"names":[],"mappings":"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"}

package/dist/ports/audit.d.ts

@@ -1,58 +1,329 @@
+/**
+ * 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 | null | number | 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"> & {
     occurredAt?: Date;
     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 declare function createAnonymousActor(options?: Omit<ActivityActor, "type">): ActivityActor;
+/**
+ * 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 declare function createServiceActor(id: string, options?: Omit<ActivityActor, "type" | "id">): ActivityActor;
+/**
+ * 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 declare function createSystemActor(id?: string, options?: Omit<ActivityActor, "type" | "id">): ActivityActor;
+/**
+ * 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 declare function createUserActor(id: string, options?: Omit<ActivityActor, "type" | "id">): ActivityActor;
+/**
+ * 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 declare function createTenant(id: string, options?: Omit<ActivityTenant, "id">): ActivityTenant;
+/**
+ * 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 declare function normalizeAuditLogEntry(entry: AuditLogEntryInput): AuditLogEntry;
+/**
+ * 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 declare 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 declare function createRedactedAuditLog(audit: AuditLogPort, options?: AuditLogOptions): AuditLogPort;
+/**
+ * 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 declare function createMemoryAuditLog(entries?: AuditLogEntry[], options?: AuditLogOptions): MemoryAuditLogPort;
 //# sourceMappingURL=audit.d.ts.map

package/dist/ports/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/ports/audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/ports/audit.ts"],"names":[],"mappings":"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"}