shelving 1.179.2 → 1.180.0

package/api/endpoint/Endpoint.d.ts

@@ -1,11 +1,11 @@
 import { type Schema } from "../../schema/Schema.js";
 import type { ImmutableArray } from "../../util/array.js";
 import { type Data } from "../../util/data.js";
-import type { AnyCaller, Arguments } from "../../util/function.js";
+import type { AnyCaller } from "../../util/function.js";
 import type { RequestMethod, RequestParams } from "../../util/http.js";
 import type { AbsolutePath } from "../../util/path.js";
 import { type TemplatePlaceholders } from "../../util/template.js";
-import type { EndpointCallback, EndpointHandler } from "./util.js";
+import type { EndpointCallback, EndpointContext, EndpointHandler } from "./util.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -44,7 +44,7 @@ export declare class Endpoint<P, R> {
      * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      * @returns An `EndpointHandler` object combining this endpoint and the callback into a single typed object.
      */
-    handler<A extends Arguments = []>(callback: EndpointCallback<P, R, A>): EndpointHandler<P, R, A>;
+    handler<C extends EndpointContext>(callback: EndpointCallback<P, R, C>): EndpointHandler<P, R, C>;
     /** Convert to string, e.g. `GET /user/{id}` */
     toString(): string;
 }

package/api/endpoint/util.d.ts

@@ -1,6 +1,12 @@
-import type { Arguments } from "../../util/function.js";
+import type { AnyCaller } from "../../util/function.js";
 import { type PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "./Endpoint.js";
+/**
+ * The second argument to an `EndpointCallback` is its context.
+ * This must contain the `Request` that triggered the callback, but may contain additional details too. */
+export interface EndpointContext {
+    readonly request: Request;
+}
 /**
  * A function that handles an endpoint request, with a payload and returns a result.
  *
@@ -11,16 +17,16 @@ import type { Endpoint } from "./Endpoint.js";
  * @returns {Response} Returning a `Response` object (this will pass back to the client without validation).
  * @returns {R} Returning the return type of the handler (this will be validated against the Endpoint's result schema).
  */
-export type EndpointCallback<P, R, A extends Arguments = []> = (payload: P, request: Request, ...args: A) => R | Response | Promise<R | Response>;
+export type EndpointCallback<P, R, C extends EndpointContext> = (payload: P, context: C) => R | Response | Promise<R | Response>;
 /** A typed endpoint definition paired with its implementation callback. */
-export interface EndpointHandler<P = unknown, R = unknown, A extends Arguments = []> {
+export interface EndpointHandler<P, R, C extends EndpointContext> {
     readonly endpoint: Endpoint<P, R>;
-    readonly callback: EndpointCallback<P, R, A>;
+    readonly callback: EndpointCallback<P, R, C>;
 }
 /** Any endpoint handler. */
-export type AnyEndpointHandler<A extends Arguments = []> = EndpointHandler<any, any, A>;
+export type AnyEndpointHandler<C extends EndpointContext = EndpointContext> = EndpointHandler<any, any, C>;
 /** A collection of endpoint handlers that can be matched and invoked by `handleEndpoints()`. */
-export type EndpointHandlers<A extends Arguments = []> = Iterable<AnyEndpointHandler<A>>;
+export type EndpointHandlers<C extends EndpointContext = EndpointContext> = Iterable<AnyEndpointHandler<C>>;
 /**
  * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
  * - The original `Request` object is passed through to the callback unchanged.
@@ -31,4 +37,4 @@ export type EndpointHandlers<A extends Arguments = []> = Iterable<AnyEndpointHan
  * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
  * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
  */
-export declare function handleEndpoints<A extends Arguments = []>(request: Request, base: PossibleURL, handlers: EndpointHandlers<A>, ...args: A): Promise<Response>;
+export declare function handleEndpoints<C extends EndpointContext>(base: PossibleURL, handlers: EndpointHandlers<C>, context: C, caller?: AnyCaller): Promise<Response>;

package/api/endpoint/util.js

@@ -14,9 +14,8 @@ import { requireURL } from "../../util/url.js";
  * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
  * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
  */
-export function handleEndpoints(request, base, handlers, ...args) {
-    const caller = handleEndpoints;
-    const { url, method } = request;
+export function handleEndpoints(base, handlers, context, caller = handleEndpoints) {
+    const { url, method } = context.request;
     if (!isRequestMethod(method))
         throw new MethodNotAllowedError("Unsupported request method", { received: method, caller });
     const { origin: baseOrigin, pathname: basePath } = requireURL(base, undefined, caller);
@@ -31,7 +30,7 @@ export function handleEndpoints(request, base, handlers, ...args) {
         if (!pathParams)
             continue;
         const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
-        return _handleEndpoint(handler, params, request, args, handleEndpoints);
+        return _handleEndpoint(handler, params, context, handleEndpoints);
     }
     throw new NotFoundError("No matching endpoint", { received: targetPath, caller });
 }
@@ -40,11 +39,11 @@ export function handleEndpoints(request, base, handlers, ...args) {
  */
 async function _handleEndpoint({ endpoint, callback }, 
 /** Params we already matched/parsed from the URL. */
-params, request, args, caller = _handleEndpoint) {
-    const content = await getRequestContent(request, caller);
+params, context, caller) {
+    const content = await getRequestContent(context.request, caller);
     const unsafePayload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
     const payload = endpoint.payload.validate(unsafePayload);
-    const unsafeResult = await callback(payload, request, ...args);
+    const unsafeResult = await callback(payload, context);
     if (unsafeResult instanceof Response)
         return unsafeResult;
     try {

package/api/index.d.ts

@@ -6,6 +6,7 @@ export * from "./provider/APIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
+export * from "./provider/MockEnpdointAPIProvider.js";
 export * from "./provider/ThroughAPIProvider.js";
 export * from "./provider/ValidationAPIProvider.js";
 export * from "./store/EndpointStore.js";

package/api/index.js

@@ -6,6 +6,7 @@ export * from "./provider/APIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/MockAPIProvider.js";
+export * from "./provider/MockEnpdointAPIProvider.js";
 export * from "./provider/ThroughAPIProvider.js";
 export * from "./provider/ValidationAPIProvider.js";
 export * from "./store/EndpointStore.js";

package/api/provider/MockEnpdointAPIProvider.d.ts

@@ -0,0 +1,16 @@
+import { type EndpointContext, type EndpointHandlers } from "../endpoint/util.js";
+import { MockAPIProvider, type MockAPIProviderOptions } from "./MockAPIProvider.js";
+/**
+ * Provider that mocks an API that calls and matches an array of `EndpointHandler` objects returned from `Endpoint.handler()`
+ * - Used to test server-side API code, calls against an API made up of multiple `Endpoint` instances.
+ *
+ * @example
+ *  const endpoint = POST("/squared", INTEGER, INTEGER); // Create an endpoint designed to square its input number.
+ *  const handlers = [endpoint.handler(num => num * num)]; // Implement handlers for the endpoints.
+ * 	const api = new MockEnpdointAPIProvider(handlers); // Create a new mock provider.
+ *  const result = await api.fetch(endpoint, 4); // Mock a call to the endpoint through the provider.
+ *  expect(result).toBe(16);
+ */
+export declare class MockEnpdointAPIProvider<C extends EndpointContext> extends MockAPIProvider {
+    constructor(handlers: EndpointHandlers<C>, c: Omit<EndpointContext, "request">, options: MockAPIProviderOptions);
+}

package/api/provider/MockEnpdointAPIProvider.js

@@ -0,0 +1,18 @@
+import { handleEndpoints } from "../endpoint/util.js";
+import { MockAPIProvider } from "./MockAPIProvider.js";
+/**
+ * Provider that mocks an API that calls and matches an array of `EndpointHandler` objects returned from `Endpoint.handler()`
+ * - Used to test server-side API code, calls against an API made up of multiple `Endpoint` instances.
+ *
+ * @example
+ *  const endpoint = POST("/squared", INTEGER, INTEGER); // Create an endpoint designed to square its input number.
+ *  const handlers = [endpoint.handler(num => num * num)]; // Implement handlers for the endpoints.
+ * 	const api = new MockEnpdointAPIProvider(handlers); // Create a new mock provider.
+ *  const result = await api.fetch(endpoint, 4); // Mock a call to the endpoint through the provider.
+ *  expect(result).toBe(16);
+ */
+export class MockEnpdointAPIProvider extends MockAPIProvider {
+    constructor(handlers, c, options) {
+        super(request => handleEndpoints(this.url, handlers, { ...c, request }), options);
+    }
+}

package/bun/BunPostgreSQLProvider.d.ts

@@ -0,0 +1,10 @@
+import type { SQL } from "bun";
+import { PostgreSQLProvider, type SQLFragment } from "../db/index.js";
+import type { ImmutableArray } from "../util/array.js";
+import type { Data } from "../util/data.js";
+export declare class BunPostgreSQLProvider extends PostgreSQLProvider {
+    private _sql;
+    constructor(sql: SQL);
+    exec<T extends Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<ImmutableArray<T>>;
+    sqlIdentifier(name: string): SQLFragment;
+}

package/bun/BunPostgreSQLProvider.js

@@ -0,0 +1,16 @@
+import { PostgreSQLProvider } from "../db/index.js";
+export class BunPostgreSQLProvider extends PostgreSQLProvider {
+    _sql;
+    constructor(sql) {
+        super();
+        this._sql = sql;
+    }
+    // Implement `SQLProvider` using `Bun.SQL` instance.
+    exec(strings, ...values) {
+        return this._sql(strings, ...values);
+    }
+    // Override to wrap identifiers using `sql()`, since Bun SQL engine supports this and it's more secure.
+    sqlIdentifier(name) {
+        return this.sql `${this._sql(name)}`;
+    }
+}

package/bun/index.d.ts

@@ -0,0 +1 @@
+export * from "./BunPostgreSQLProvider.js";

package/bun/index.js

@@ -0,0 +1 @@
+export * from "./BunPostgreSQLProvider.js";

package/cloudflare/CloudflareD1Provider.d.ts

@@ -0,0 +1,14 @@
+import { SQLiteProvider } from "../db/provider/SQLiteProvider.js";
+import { type ImmutableArray } from "../util/array.js";
+import type { Data } from "../util/data.js";
+import type { D1Database } from "./types.js";
+/**
+ * Cloudflare D1 database provider.
+ *
+ * Uses the D1 Worker API for execution and standard SQL from `SQLProvider`.
+ */
+export declare class CloudflareD1Provider extends SQLiteProvider {
+    private readonly _db;
+    constructor(db: D1Database);
+    exec<T extends Data = Data>(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): Promise<readonly T[]>;
+}

package/cloudflare/CloudflareD1Provider.js

@@ -0,0 +1,56 @@
+import { SQLiteProvider } from "../db/provider/SQLiteProvider.js";
+import { ValueError } from "../error/ValueError.js";
+import { isArray } from "../util/array.js";
+import { isPlainObject } from "../util/object.js";
+/**
+ * Cloudflare D1 database provider.
+ *
+ * Uses the D1 Worker API for execution and standard SQL from `SQLProvider`.
+ */
+export class CloudflareD1Provider extends SQLiteProvider {
+    _db;
+    constructor(db) {
+        super();
+        this._db = db;
+    }
+    async exec(strings, ...values) {
+        const { query, values: bindings } = _getD1Query(strings, values, this.exec);
+        const result = await this._db
+            .prepare(query)
+            .bind(...bindings)
+            .run();
+        return result.results ?? [];
+    }
+}
+function _getD1Query(strings, values, caller) {
+    let query = strings[0] ?? "";
+    const bindings = [];
+    for (const [index, value] of values.entries()) {
+        const part = _getD1Part(value, caller);
+        query += part.query;
+        bindings.push(...part.values);
+        query += strings[index + 1] ?? "";
+    }
+    return { query, values: bindings };
+}
+function _getD1Part(value, caller) {
+    if (_isSQLQuery(value))
+        return _getD1Query(value.strings, value.values, caller);
+    return { query: "?", values: [_getD1Value(value, caller)] };
+}
+function _getD1Value(value, caller) {
+    if (value === null || typeof value === "boolean" || typeof value === "string" || typeof value === "number")
+        return value;
+    if (isArray(value) || isPlainObject(value)) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch (cause) {
+            throw new ValueError("Cannot convert value to D1 JSON value", { cause, received: value, caller });
+        }
+    }
+    throw new ValueError("Cannot convert value to D1 binding", { received: value, caller });
+}
+function _isSQLQuery(value) {
+    return typeof value === "object" && !!value && "strings" in value && "values" in value;
+}

package/cloudflare/CloudflareKVProvider.d.ts

@@ -4,14 +4,7 @@ import type { Data } from "../util/data.js";
 import type { Items, OptionalItem } from "../util/item.js";
 import type { ItemQuery } from "../util/query.js";
 import type { Updates } from "../util/update.js";
-/** Minimal interface matching Cloudflare Workers KV namespace runtime object. */
-export interface KVNamespace {
-    get(key: string, options: {
-        type: "json";
-    }): Promise<unknown>;
-    put(key: string, value: string): Promise<void>;
-    delete(key: string): Promise<void>;
-}
+import type { KVNamespace } from "./types.js";
 /**
  * Cloudflare Workers KV database provider.
  *
@@ -49,5 +42,5 @@ export declare class CloudflareKVProvider extends DBProvider<string> {
     getQuerySequence<T extends Data>(_c: Collection<string, string, T>, _q?: ItemQuery<string, T>): AsyncIterable<Items<string, T>>;
     setQuery<T extends Data>(_c: Collection<string, string, T>, _q: ItemQuery<string, T>, _data: T): Promise<void>;
     updateQuery<T extends Data>(_c: Collection<string, string, T>, _q: ItemQuery<string, T>, _updates: Updates<T>): Promise<void>;
-    deleteQuery<T extends Data>(c: Collection<string, string, T>, _q: ItemQuery<string, T>): Promise<void>;
+    deleteQuery<T extends Data>(_c: Collection<string, string, T>, _q: ItemQuery<string, T>): Promise<void>;
 }

package/cloudflare/CloudflareKVProvider.js

@@ -66,7 +66,7 @@ export class CloudflareKVProvider extends DBProvider {
     async updateQuery(_c, _q, _updates) {
         throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
     }
-    async deleteQuery(c, _q) {
+    async deleteQuery(_c, _q) {
         throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
 }

package/cloudflare/index.d.ts

@@ -1 +1,3 @@
+export * from "./CloudflareD1Provider.js";
 export * from "./CloudflareKVProvider.js";
+export * from "./types.js";

package/cloudflare/index.js

@@ -1 +1,3 @@
+export * from "./CloudflareD1Provider.js";
 export * from "./CloudflareKVProvider.js";
+export * from "./types.js";

package/cloudflare/types.d.ts

@@ -0,0 +1,44 @@
+/** Minimal interface matching Cloudflare Workers KV namespace runtime object. */
+export interface KVNamespace {
+    get(key: string, options: {
+        type: "json";
+    }): Promise<unknown>;
+    put(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Value that can be passed through the D1 Worker API. */
+export type D1Value = boolean | null | number | string;
+/** Metadata returned by the D1 Worker API. */
+export interface D1Meta {
+    readonly changed_db?: boolean | undefined;
+    readonly duration?: number | undefined;
+    readonly last_row_id?: number | undefined;
+    readonly rows_read?: number | undefined;
+    readonly rows_written?: number | undefined;
+}
+/** Result object returned by `D1PreparedStatement.run()`. */
+export interface D1Result<T extends Record<string, unknown> = Record<string, unknown>> {
+    readonly success: boolean;
+    readonly meta?: D1Meta | undefined;
+    readonly results?: readonly T[] | undefined;
+}
+/** Result object returned by `D1Database.exec()`. */
+export interface D1ExecResult {
+    readonly count: number;
+    readonly duration: number;
+}
+/** Minimal prepared statement interface for D1 databases and sessions. */
+export interface D1PreparedStatement {
+    bind(...values: D1Value[]): D1PreparedStatement;
+    first<T = Record<string, unknown>>(column?: string): Promise<T | null>;
+    raw<T = unknown[]>(options?: {
+        columnNames?: boolean;
+    }): Promise<readonly T[]>;
+    run<T extends Record<string, unknown> = Record<string, unknown>>(): Promise<D1Result<T>>;
+}
+/** Minimal D1 binding/session interface used by `CloudflareD1Provider`. */
+export interface D1Database {
+    batch<T extends Record<string, unknown> = Record<string, unknown>>(statements: readonly D1PreparedStatement[]): Promise<readonly D1Result<T>[]>;
+    exec?(query: string): Promise<D1ExecResult>;
+    prepare(query: string): D1PreparedStatement;
+}

package/cloudflare/types.js

@@ -0,0 +1 @@
+export {};

package/db/collection/Collection.d.ts

@@ -17,8 +17,8 @@ export declare class Collection<K extends string, I extends Identifier, T extend
 }
 /** Shortcut factory for creating a Collection. */
 export declare function COLLECTION<K extends string, I extends Identifier, T extends Data>(name: K, id: Schema<I>, data: Schemas<T> | DataSchema<T>): Collection<K, I, T>;
-/** A readonly array of Collection instances. */
-export type Collections = ReadonlyArray<Collection<string, Identifier, Data>>;
+/** A readonly array of Collection instances, possibly with a standardised `Identifier`. */
+export type Collections<I extends Identifier = Identifier> = ReadonlyArray<Collection<string, I, Data>>;
 /** Extract the union of collection key strings from a Collections type. */
 export type CollectionKeys<C extends Collections> = C[number]["name"];
 /** Convert a Collections array type to a Database-style object mapping. */

package/db/index.d.ts

@@ -1,10 +1,17 @@
 export * from "./collection/Collection.js";
+export * from "./migrate/DBMigrator.js";
+export * from "./migrate/PostgreSQLMigrator.js";
+export * from "./migrate/SQLiteMigrator.js";
+export * from "./migrate/SQLMigrator.js";
 export * from "./provider/CacheDBProvider.js";
 export * from "./provider/ChangesDBProvider.js";
 export * from "./provider/DBProvider.js";
 export * from "./provider/DebugDBProvider.js";
 export * from "./provider/MemoryDBProvider.js";
 export * from "./provider/MockDBProvider.js";
+export * from "./provider/PostgreSQLProvider.js";
+export * from "./provider/SQLiteProvider.js";
+export * from "./provider/SQLProvider.js";
 export * from "./provider/ThroughDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";

package/db/index.js

@@ -1,10 +1,17 @@
 export * from "./collection/Collection.js";
+export * from "./migrate/DBMigrator.js";
+export * from "./migrate/PostgreSQLMigrator.js";
+export * from "./migrate/SQLiteMigrator.js";
+export * from "./migrate/SQLMigrator.js";
 export * from "./provider/CacheDBProvider.js";
 export * from "./provider/ChangesDBProvider.js";
 export * from "./provider/DBProvider.js";
 export * from "./provider/DebugDBProvider.js";
 export * from "./provider/MemoryDBProvider.js";
 export * from "./provider/MockDBProvider.js";
+export * from "./provider/PostgreSQLProvider.js";
+export * from "./provider/SQLiteProvider.js";
+export * from "./provider/SQLProvider.js";
 export * from "./provider/ThroughDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";

package/db/migrate/DBMigrator.d.ts

@@ -0,0 +1,8 @@
+import type { Collections } from "../collection/Collection.js";
+import type { DBProvider } from "../provider/DBProvider.js";
+/** Base class for database schema migrators. */
+export declare abstract class DBMigrator<T extends DBProvider = DBProvider> {
+    readonly provider: T;
+    constructor(provider: T);
+    abstract migrate(...collections: Collections): Promise<void>;
+}

package/db/migrate/DBMigrator.js

@@ -0,0 +1,7 @@
+/** Base class for database schema migrators. */
+export class DBMigrator {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+}

package/db/migrate/PostgreSQLMigrator.d.ts

@@ -0,0 +1,37 @@
+import type { Schema } from "../../schema/Schema.js";
+import type { Data } from "../../util/data.js";
+import type { Identifier } from "../../util/item.js";
+import type { Collection } from "../collection/Collection.js";
+import type { SQLProvider } from "../provider/SQLProvider.js";
+import { SQLMigrator, type SQLTable, type SQLTableColumn } from "./SQLMigrator.js";
+type PostgreSQLColumnRow = {
+    readonly generated: boolean;
+    readonly identity: boolean;
+    readonly name: string;
+    readonly nullable: boolean;
+    readonly primary: boolean;
+    readonly type: string;
+    readonly value: string | null;
+};
+/** PostgreSQL migrator using pg_catalog-style schema inspection. */
+export declare class PostgreSQLMigrator<T extends SQLProvider = SQLProvider> extends SQLMigrator<T> {
+    protected getTables(): Promise<readonly string[]>;
+    protected getTable(name: string): Promise<SQLTable | undefined>;
+    protected getCreateTableSuffix<TData extends Data>(_collection: Collection<string, Identifier, TData>): string;
+    protected getDataColumnDefinition(): string;
+    protected getGeneratedColumnDefinition(_columnName: string, path: string, definition: string): string;
+    protected getIDColumnDefinition<TData extends Data>(collection: Collection<string, Identifier, TData>): string;
+    protected getAlterColumnQueries(tableName: string, from: SQLTableColumn, to: SQLTableColumn): readonly string[];
+    protected definition<TValue>(schema: Schema<TValue>): string | undefined;
+    protected getCurrentColumnStatement({ generated, identity, name: _name, nullable, primary, type, value }: PostgreSQLColumnRow): string;
+    protected getGeneratedExpression(path: string, definition: string): string;
+    protected getGeneratedCast(definition: string): string | undefined;
+    protected parseColumn({ name, statement }: SQLTableColumn): {
+        readonly defaultValue?: string | undefined;
+        readonly generated: boolean;
+        readonly name: string;
+        readonly nullable: boolean;
+        readonly type: string;
+    } | undefined;
+}
+export {};