@beignet/core 0.0.1 → 0.0.3

package/dist/testing/index.d.ts

@@ -0,0 +1,171 @@
+import { type ClockPort } from "../ports/clock";
+import { type IdGeneratorPort } from "../ports/id-generator";
+/**
+ * Value that may be returned synchronously or asynchronously.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Arguments passed to a factory default builder.
+ */
+export interface FactoryBuildArgs<Name extends string = string> {
+    /**
+     * Factory name.
+     */
+    readonly name: Name;
+    /**
+     * Current sequence value.
+     */
+    readonly sequence: number;
+    /**
+     * ID generator available to the factory.
+     */
+    readonly ids: IdGeneratorPort;
+    /**
+     * Clock available to the factory.
+     */
+    readonly clock: ClockPort;
+}
+/**
+ * Arguments passed to a factory persistence function.
+ */
+export type FactoryPersistArgs<Name extends string = string> = FactoryBuildArgs<Name>;
+/**
+ * Overrides accepted by factory build and create methods.
+ */
+export type FactoryOverrides<Value extends object, Name extends string = string> = Partial<Value> | ((value: Value, args: FactoryBuildArgs<Name>) => Partial<Value>);
+/**
+ * Options for declaring a test data factory.
+ */
+export interface DefineFactoryOptions<Name extends string, Value extends object, Ctx = unknown, Created = Value> {
+    /**
+     * Build the default value for the current sequence.
+     */
+    defaults(args: FactoryBuildArgs<Name>): Value;
+    /**
+     * Persist a built value and return the created record.
+     */
+    persist?(ctx: Ctx, value: Value, args: FactoryPersistArgs<Name>): MaybePromise<Created>;
+    /**
+     * ID generator to expose to the factory.
+     */
+    ids?: IdGeneratorPort;
+    /**
+     * Clock to expose to the factory.
+     */
+    clock?: ClockPort;
+    /**
+     * Initial sequence number. Defaults to `1`.
+     */
+    start?: number;
+}
+/**
+ * Declared test data factory.
+ */
+export interface FactoryDef<Name extends string = string, Value extends object = object, Ctx = unknown, Created = Value> {
+    /**
+     * Discriminator for factory definitions.
+     */
+    readonly kind: "factory";
+    /**
+     * Factory name.
+     */
+    readonly name: Name;
+    /**
+     * Build an in-memory value.
+     */
+    build(overrides?: FactoryOverrides<Value, Name>): Value;
+    /**
+     * Build multiple in-memory values.
+     */
+    buildList(count: number, overrides?: FactoryOverrides<Value, Name>): Value[];
+    /**
+     * Build and persist a value.
+     */
+    create(ctx: Ctx, overrides?: FactoryOverrides<Value, Name>): Promise<Created>;
+    /**
+     * Build and persist multiple values.
+     */
+    createList(ctx: Ctx, count: number, overrides?: FactoryOverrides<Value, Name>): Promise<Created[]>;
+    /**
+     * Reset the factory sequence.
+     */
+    resetSequence(next?: number): void;
+}
+/**
+ * Options for declaring a seed.
+ */
+export interface DefineSeedOptions<Ctx> {
+    /**
+     * Optional human-readable seed description.
+     */
+    description?: string;
+    /**
+     * Execute the seed.
+     */
+    run(ctx: Ctx): MaybePromise<void>;
+}
+/**
+ * Declared seed that can be run with `runSeeds(...)`.
+ */
+export interface SeedDef<Ctx = unknown, Name extends string = string> {
+    /**
+     * Discriminator for seed definitions.
+     */
+    readonly kind: "seed";
+    /**
+     * Seed name.
+     */
+    readonly name: Name;
+    /**
+     * Optional human-readable seed description.
+     */
+    readonly description?: string;
+    /**
+     * Execute the seed.
+     */
+    run(ctx: Ctx): MaybePromise<void>;
+}
+/**
+ * Options for running a list of seeds.
+ */
+export interface RunSeedsOptions<Ctx> {
+    /**
+     * Context passed to every seed.
+     */
+    ctx: Ctx;
+    /**
+     * Seeds to run in order.
+     */
+    seeds: readonly SeedDef<Ctx>[];
+}
+/**
+ * Error thrown when a seed fails.
+ */
+export declare class SeedRunError extends Error {
+    /**
+     * Seed that failed.
+     */
+    readonly seed: SeedDef;
+    /**
+     * Original thrown value.
+     */
+    readonly cause: unknown;
+    constructor(seed: SeedDef, cause: unknown);
+}
+/**
+ * Reset one or more factory sequences to their configured starting values.
+ */
+export declare function resetFactories(...factories: readonly Pick<FactoryDef, "resetSequence">[]): void;
+/**
+ * Define a typed test data factory with deterministic sequence support.
+ */
+export declare function defineFactory<const Name extends string, Value extends object, Ctx = unknown, Created = Value>(name: Name, options: DefineFactoryOptions<Name, Value, Ctx, Created>): FactoryDef<Name, Value, Ctx, Created>;
+/**
+ * Define a named seed.
+ */
+export declare function defineSeed<const Name extends string, Ctx = unknown>(name: Name, options: DefineSeedOptions<Ctx>): SeedDef<Ctx, Name>;
+/**
+ * Run seeds in order and wrap failures with the seed name.
+ */
+export declare function runSeeds<Ctx>(options: RunSeedsOptions<Ctx>): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/testing/index.js

@@ -0,0 +1,127 @@
+import { createSystemClock } from "../ports/clock";
+import { createUuidIdGenerator, } from "../ports/id-generator";
+/**
+ * Error thrown when a seed fails.
+ */
+export class SeedRunError extends Error {
+    /**
+     * Seed that failed.
+     */
+    seed;
+    /**
+     * Original thrown value.
+     */
+    cause;
+    constructor(seed, cause) {
+        super(`Seed "${seed.name}" failed: ${errorMessage(cause)}`);
+        this.name = "SeedRunError";
+        this.seed = seed;
+        this.cause = cause;
+    }
+}
+/**
+ * Reset one or more factory sequences to their configured starting values.
+ */
+export function resetFactories(...factories) {
+    for (const factory of factories) {
+        factory.resetSequence();
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function factoryArgs(args) {
+    return args;
+}
+function applyOverrides(value, args, overrides) {
+    if (!overrides)
+        return value;
+    const resolved = typeof overrides === "function" ? overrides(value, args) : overrides;
+    return {
+        ...value,
+        ...resolved,
+    };
+}
+function assertCount(kind, count) {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new Error(`Factory ${kind} count must be a non-negative integer.`);
+    }
+}
+/**
+ * Define a typed test data factory with deterministic sequence support.
+ */
+export function defineFactory(name, options) {
+    const start = options.start ?? 1;
+    const ids = options.ids ?? createUuidIdGenerator();
+    const clock = options.clock ?? createSystemClock();
+    let nextSequence = start;
+    function build(overrides) {
+        const args = factoryArgs({
+            name,
+            sequence: nextSequence++,
+            ids,
+            clock,
+        });
+        const value = options.defaults(args);
+        return applyOverrides(value, args, overrides);
+    }
+    async function create(ctx, overrides) {
+        if (!options.persist) {
+            throw new Error(`Factory "${name}" cannot create persisted records without a persist function.`);
+        }
+        const value = build(overrides);
+        const args = factoryArgs({
+            name,
+            sequence: nextSequence - 1,
+            ids,
+            clock,
+        });
+        return options.persist(ctx, value, args);
+    }
+    return {
+        kind: "factory",
+        name,
+        build,
+        buildList(count, overrides) {
+            assertCount("buildList", count);
+            return Array.from({ length: count }, () => build(overrides));
+        },
+        create,
+        async createList(ctx, count, overrides) {
+            assertCount("createList", count);
+            const created = [];
+            for (let index = 0; index < count; index += 1) {
+                created.push(await create(ctx, overrides));
+            }
+            return created;
+        },
+        resetSequence(next = start) {
+            nextSequence = next;
+        },
+    };
+}
+/**
+ * Define a named seed.
+ */
+export function defineSeed(name, options) {
+    return {
+        kind: "seed",
+        name,
+        description: options.description,
+        run: options.run,
+    };
+}
+/**
+ * Run seeds in order and wrap failures with the seed name.
+ */
+export async function runSeeds(options) {
+    for (const seed of options.seeds) {
+        try {
+            await seed.run(options.ctx);
+        }
+        catch (error) {
+            throw new SeedRunError(seed, error);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

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

package/dist/uploads/client.d.ts

@@ -0,0 +1,278 @@
+import type { CompleteUploadResult, InferUploadMetadata, InferUploadResult, PreparedUploadFile, PrepareUploadResult, UploadDef, UploadFileConstraints, UploadFromRegistry, UploadManifestEntry, UploadRegistry } from "./index";
+/**
+ * Upload registry shape accepted by the typed browser client.
+ *
+ * Pass the type of a `defineUploads(...)` registry, or an upload definition
+ * array, to `createUploadClient<...>()`.
+ */
+export type UploadClientRegistry = UploadRegistry | readonly UploadDef[];
+/**
+ * Union of upload route names available in an upload registry.
+ */
+export type UploadClientName<Registry> = UploadFromRegistry<Registry> extends UploadDef<infer Name> ? Name & string : never;
+/**
+ * Find one upload definition in a registry by its route name.
+ */
+export type UploadByName<Registry, Name extends string> = UploadFromRegistry<Registry> extends infer Upload ? Upload extends UploadDef ? Upload extends {
+    readonly name: Name;
+} ? Upload : never : never : never;
+/**
+ * Transport strategy used by `upload(...)`.
+ */
+export type UploadClientStrategy = "auto" | "direct" | "server";
+/**
+ * Fetch-compatible function used for upload route and direct provider
+ * requests.
+ */
+export type UploadClientFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Static or lazy headers sent to Beignet upload route requests.
+ */
+export type UploadClientHeaders = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+/**
+ * Request options shared by Beignet upload route requests.
+ */
+export interface UploadClientRequestOptions {
+    /**
+     * Browser credential policy for upload route requests.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Browser request mode for upload route requests.
+     */
+    mode?: RequestMode;
+    /**
+     * Browser cache policy for upload route requests.
+     */
+    cache?: RequestCache;
+}
+/**
+ * Options for `createUploadClient(...)`.
+ */
+export interface CreateUploadClientOptions {
+    /**
+     * Base URL for the upload route.
+     *
+     * @default "/api/uploads"
+     */
+    baseUrl?: string;
+    /**
+     * Fetch implementation used for Beignet upload route requests.
+     */
+    fetch?: UploadClientFetch;
+    /**
+     * Headers sent to Beignet upload route requests. These are not sent to
+     * provider-owned direct upload URLs.
+     */
+    headers?: UploadClientHeaders;
+    /**
+     * Request options shared by Beignet upload route requests.
+     */
+    request?: UploadClientRequestOptions;
+    /**
+     * Optional client-safe upload metadata for UI helpers.
+     */
+    manifest?: readonly UploadManifestEntry[];
+}
+/**
+ * File lifecycle event emitted by direct and server upload helpers.
+ */
+export interface UploadClientFileEvent {
+    /**
+     * Browser `File` object being uploaded.
+     */
+    file: File;
+    /**
+     * File name supplied by the browser.
+     */
+    fileName: string;
+    /**
+     * Zero-based index from the files array passed by the caller.
+     */
+    index: number;
+    /**
+     * Prepared upload id when the file has gone through `prepare(...)`.
+     */
+    uploadId?: string;
+    /**
+     * Storage key when the file has gone through `prepare(...)`.
+     */
+    key?: string;
+}
+/**
+ * Upload progress event emitted while a direct upload is in flight.
+ */
+export interface UploadClientProgressEvent extends UploadClientFileEvent {
+    /**
+     * Uploaded bytes.
+     */
+    loaded: number;
+    /**
+     * Total bytes expected for the file.
+     */
+    total: number;
+    /**
+     * Fraction from `0` to `1`.
+     */
+    progress: number;
+}
+/**
+ * Per-call options shared by upload client route requests.
+ */
+export interface UploadClientRouteOptions {
+    /**
+     * Additional headers sent to Beignet upload route requests.
+     */
+    headers?: UploadClientHeaders;
+    /**
+     * Additional request options sent to Beignet upload route requests.
+     */
+    request?: UploadClientRequestOptions;
+    /**
+     * Abort signal used for route requests and direct uploads.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for preparing an upload.
+ */
+export interface UploadClientPrepareOptions<Upload extends UploadDef> extends UploadClientRouteOptions {
+    /**
+     * Metadata validated by the upload definition.
+     */
+    metadata: InferUploadMetadata<Upload>;
+    /**
+     * Browser files to upload.
+     */
+    files: readonly File[];
+}
+/**
+ * Options for direct, server, or automatic upload execution.
+ */
+export interface UploadClientUploadOptions<Upload extends UploadDef> extends UploadClientPrepareOptions<Upload> {
+    /**
+     * Upload transport strategy. Auto probes for direct-upload instructions and
+     * falls back to server-handled multipart upload.
+     *
+     * @default "auto"
+     */
+    strategy?: UploadClientStrategy;
+    /**
+     * Called when a file is about to be uploaded.
+     */
+    onFileBegin?(event: UploadClientFileEvent): void;
+    /**
+     * Called with upload progress. Direct uploads use XHR when this callback is
+     * provided so browsers can report progress events.
+     */
+    onProgress?(event: UploadClientProgressEvent): void;
+}
+/**
+ * Browser upload client typed by an upload registry.
+ */
+export interface UploadClient<Registry extends UploadClientRegistry> {
+    /**
+     * Validate metadata and file intent, authorize the upload, and receive
+     * storage keys plus direct upload instructions when a signer is configured.
+     */
+    prepare<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientPrepareOptions<UploadByName<Registry, Name>>): Promise<PrepareUploadResult>;
+    /**
+     * Complete a prepared direct upload after objects have been written to
+     * storage.
+     */
+    complete<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientRouteOptions & {
+        metadata: InferUploadMetadata<UploadByName<Registry, Name>>;
+        files: readonly PreparedUploadFile[];
+    }): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
+    /**
+     * Upload files through the Beignet application server using multipart form
+     * data.
+     */
+    server<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientUploadOptions<UploadByName<Registry, Name>>): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
+    /**
+     * Require a direct provider upload flow: prepare, PUT each file to its
+     * provider URL, then complete.
+     */
+    direct<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientUploadOptions<UploadByName<Registry, Name>>): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
+    /**
+     * Upload using the selected strategy. The default `"auto"` strategy uses a
+     * direct provider flow when available and falls back to server multipart.
+     */
+    upload<Name extends UploadClientName<Registry>>(uploadName: Name, options: UploadClientUploadOptions<UploadByName<Registry, Name>>): Promise<CompleteUploadResult<InferUploadResult<UploadByName<Registry, Name>>>>;
+    /**
+     * Return manifest-backed file constraints for UI controls.
+     */
+    constraints<Name extends UploadClientName<Registry>>(uploadName: Name): UploadFileConstraints | undefined;
+    /**
+     * Return a comma-delimited file input `accept` value from manifest content
+     * types.
+     */
+    accept<Name extends UploadClientName<Registry>>(uploadName: Name): string | undefined;
+}
+/**
+ * Constructor options for `UploadClientError`.
+ */
+export interface UploadClientErrorOptions {
+    /**
+     * Client operation that failed.
+     */
+    operation: string;
+    /**
+     * Upload route name involved in the failure.
+     */
+    uploadName: string;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+    /**
+     * HTTP status when a route or provider response was received.
+     */
+    status?: number;
+    /**
+     * Machine-readable error code.
+     */
+    code?: string;
+    /**
+     * Structured error details from the upload route, when available.
+     */
+    details?: unknown;
+    /**
+     * Original error that caused the client failure.
+     */
+    cause?: unknown;
+}
+/**
+ * Error thrown by upload client route requests or direct provider uploads.
+ */
+export declare class UploadClientError extends Error {
+    /**
+     * Client operation that failed.
+     */
+    readonly operation: string;
+    /**
+     * Upload route name involved in the failure.
+     */
+    readonly uploadName: string;
+    /**
+     * HTTP status when a route or provider response was received.
+     */
+    readonly status?: number;
+    /**
+     * Machine-readable error code.
+     */
+    readonly code?: string;
+    /**
+     * Structured error details from the upload route, when available.
+     */
+    readonly details?: unknown;
+    /**
+     * Create an upload client error.
+     */
+    constructor(options: UploadClientErrorOptions);
+}
+/**
+ * Create a typed browser upload client for a Beignet upload route.
+ */
+export declare function createUploadClient<Registry extends UploadClientRegistry = UploadRegistry>(options?: CreateUploadClientOptions): UploadClient<Registry>;
+//# sourceMappingURL=client.d.ts.map

package/dist/uploads/client.d.ts.map

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