@dalgo/dalgo2postgrest 0.0.0-bootstrap.0 → 0.2.1

package/dist/cursor.d.ts

@@ -0,0 +1,60 @@
+import { UnsupportedError } from "@dalgo/core";
+/** Stable, adapter-owned cursor identity. A cursor from another adapter is foreign. */
+export declare const POSTGREST_CURSOR_ADAPTER = "@dalgo/dalgo2postgrest";
+export declare const POSTGREST_CURSOR_VERSION = 1;
+export type PostgrestCursorValue = string | number | boolean | null;
+export type PostgrestOrderDirection = "asc" | "desc";
+export interface PostgrestCursorOrder {
+    /** Physical PostgREST column, already mapped from a DALgo field. */
+    readonly field: string;
+    readonly direction: PostgrestOrderDirection;
+}
+/**
+ * The immutable part of a cursor. Every value that can change the meaning of a
+ * continuation is bound here so a cursor from another endpoint, relation, role
+ * scope, filter, order, projection or page size is refused instead of silently
+ * returning a different result set.
+ */
+export interface PostgrestCursorBinding {
+    readonly endpoint: string;
+    readonly collection: string;
+    readonly relation: string;
+    readonly schema?: string;
+    readonly idColumn: string;
+    readonly select: "*";
+    readonly filters: readonly (readonly [string, string])[];
+    readonly orders: readonly PostgrestCursorOrder[];
+    readonly limit: number;
+    readonly identityScope?: string;
+}
+export type PostgrestCursorErrorReason = "malformed" | "foreign" | "changed-query";
+/**
+ * A refused cursor. It extends `UnsupportedError` so callers that already guard
+ * deliberate adapter refusals keep working. The message never contains row
+ * values, headers, tokens or a transport error.
+ */
+export declare class PostgrestCursorError extends UnsupportedError {
+    readonly reason: PostgrestCursorErrorReason;
+    constructor(reason: PostgrestCursorErrorReason);
+}
+/**
+ * Encodes the next-page position as one opaque base64url token. The token is
+ * integrity-checked by comparing its complete binding with the current query;
+ * it is not a capability and must never be treated as an authorization token.
+ */
+export declare function encodePostgrestCursor(binding: PostgrestCursorBinding, page: number, values: readonly unknown[], maxBytes: number): string;
+export interface DecodedPostgrestCursor {
+    readonly page: number;
+    readonly values: readonly PostgrestCursorValue[];
+}
+/** Decodes a cursor and proves it belongs to the exact current query. */
+export declare function decodePostgrestCursor(cursor: string, binding: PostgrestCursorBinding, maxBytes: number): DecodedPostgrestCursor;
+/**
+ * Builds the PostgREST `or` expression for keyset continuation after one row.
+ *
+ * PostgREST/PostgreSQL defaults are used: `asc` sorts nulls last and `desc`
+ * sorts nulls first. The caller must append the configured primary key as a
+ * final non-null tie-breaker; this function relies on that final key to make a
+ * continuation expressible even when a user order column is null.
+ */
+export declare function postgrestKeysetFilter(orders: readonly PostgrestCursorOrder[], values: readonly PostgrestCursorValue[]): string;

package/dist/cursor.js

@@ -0,0 +1,261 @@
+import { UnsupportedError } from "@dalgo/core";
+import { postgrestFieldKey } from "./fields.js";
+import { isUnsafeNativeNumber, parseLosslessJson } from "./json.js";
+/** Stable, adapter-owned cursor identity. A cursor from another adapter is foreign. */
+export const POSTGREST_CURSOR_ADAPTER = "@dalgo/dalgo2postgrest";
+export const POSTGREST_CURSOR_VERSION = 1;
+/**
+ * A refused cursor. It extends `UnsupportedError` so callers that already guard
+ * deliberate adapter refusals keep working. The message never contains row
+ * values, headers, tokens or a transport error.
+ */
+export class PostgrestCursorError extends UnsupportedError {
+    reason;
+    constructor(reason) {
+        super(`PostgREST query cursor (${reason})`);
+        this.reason = reason;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function cursorValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || Object.is(value, -0) || isUnsafeNativeNumber(value)) {
+            throw new TypeError("PostgREST query cursor numbers must be finite, lossless and not -0");
+        }
+        return value;
+    }
+    throw new UnsupportedError("PostgREST query cursor values");
+}
+function scalar(value) {
+    if (value === null)
+        return "null";
+    // Keyset terms live inside the `or=(...)` expression, a PostgREST list
+    // context, so a string operand must be quoted and escaped there.
+    if (typeof value === "string")
+        return `"${value.replaceAll(/(["\\])/gu, "\\$1")}"`;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || Object.is(value, -0) || isUnsafeNativeNumber(value)) {
+            throw new TypeError("PostgREST query cursor numbers must be finite, lossless and not -0");
+        }
+        return String(value);
+    }
+    return String(value);
+}
+function equality(order, value) {
+    const field = postgrestFieldKey(order.field);
+    return value === null ? `${field}.is.null` : `${field}.eq.${scalar(value)}`;
+}
+function encodedTextLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function base64UrlEncode(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+function base64UrlDecode(value) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value))
+        throw new PostgrestCursorError("malformed");
+    const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+    let binary;
+    try {
+        binary = atob(`${base64}${"=".repeat((4 - (base64.length % 4)) % 4)}`);
+    }
+    catch {
+        throw new PostgrestCursorError("malformed");
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new PostgrestCursorError("malformed");
+    }
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sameBinding(left, right) {
+    return left.endpoint === right.endpoint
+        && left.collection === right.collection
+        && left.relation === right.relation
+        && left.schema === right.schema
+        && left.idColumn === right.idColumn
+        && left.select === right.select
+        && left.limit === right.limit
+        && left.identityScope === right.identityScope
+        && left.filters.length === right.filters.length
+        && left.filters.every((filter, index) => {
+            const other = right.filters[index];
+            return other !== undefined && filter[0] === other[0] && filter[1] === other[1];
+        })
+        && left.orders.length === right.orders.length
+        && left.orders.every((order, index) => {
+            const other = right.orders[index];
+            return other !== undefined && order.field === other.field && order.direction === other.direction;
+        });
+}
+function parseOrders(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new PostgrestCursorError("malformed");
+    return value.map((order) => {
+        if (!isPlainObject(order) || typeof order.field !== "string" || (order.direction !== "asc" && order.direction !== "desc")) {
+            throw new PostgrestCursorError("malformed");
+        }
+        return { field: order.field, direction: order.direction };
+    });
+}
+function parseFilters(value) {
+    if (!Array.isArray(value))
+        throw new PostgrestCursorError("malformed");
+    return value.map((filter) => {
+        if (!Array.isArray(filter) || filter.length !== 2 || typeof filter[0] !== "string" || typeof filter[1] !== "string") {
+            throw new PostgrestCursorError("malformed");
+        }
+        return [filter[0], filter[1]];
+    });
+}
+function parseValues(value, expected) {
+    if (!Array.isArray(value) || value.length !== expected)
+        throw new PostgrestCursorError("malformed");
+    return value.map((item) => {
+        if (item === null || typeof item === "string" || typeof item === "boolean")
+            return item;
+        if (typeof item === "number" && Number.isFinite(item) && !Object.is(item, -0) && !isUnsafeNativeNumber(item))
+            return item;
+        throw new PostgrestCursorError("malformed");
+    });
+}
+/**
+ * Encodes the next-page position as one opaque base64url token. The token is
+ * integrity-checked by comparing its complete binding with the current query;
+ * it is not a capability and must never be treated as an authorization token.
+ */
+export function encodePostgrestCursor(binding, page, values, maxBytes) {
+    if (!Number.isSafeInteger(page) || page < 2)
+        throw new TypeError("PostgREST query cursor page must be at least 2");
+    const encodedValues = values.map(cursorValue);
+    if (encodedValues.length !== binding.orders.length)
+        throw new TypeError("PostgREST query cursor value count does not match its order");
+    const payload = {
+        adapter: POSTGREST_CURSOR_ADAPTER,
+        version: POSTGREST_CURSOR_VERSION,
+        ...binding,
+        page,
+        values: encodedValues,
+    };
+    const encoded = base64UrlEncode(JSON.stringify(payload));
+    if (encodedTextLength(encoded) > maxBytes)
+        throw new RangeError("PostgREST query cursor exceeds maxCursorBytes");
+    return encoded;
+}
+/** Decodes a cursor and proves it belongs to the exact current query. */
+export function decodePostgrestCursor(cursor, binding, maxBytes) {
+    if (encodedTextLength(cursor) > maxBytes)
+        throw new PostgrestCursorError("malformed");
+    let value;
+    try {
+        value = parseLosslessJson(base64UrlDecode(cursor));
+    }
+    catch (error) {
+        if (error instanceof PostgrestCursorError)
+            throw error;
+        throw new PostgrestCursorError("malformed");
+    }
+    if (!isPlainObject(value) || value.adapter !== POSTGREST_CURSOR_ADAPTER)
+        throw new PostgrestCursorError("foreign");
+    if (value.version !== POSTGREST_CURSOR_VERSION)
+        throw new PostgrestCursorError("foreign");
+    if (typeof value.endpoint !== "string"
+        || typeof value.collection !== "string"
+        || typeof value.relation !== "string"
+        || (value.schema !== undefined && typeof value.schema !== "string")
+        || typeof value.idColumn !== "string"
+        || value.select !== "*"
+        || !Number.isSafeInteger(value.limit)
+        || (value.identityScope !== undefined && typeof value.identityScope !== "string")
+        || !Number.isSafeInteger(value.page)
+        || value.page < 2) {
+        throw new PostgrestCursorError("malformed");
+    }
+    const parsedBinding = {
+        endpoint: value.endpoint,
+        collection: value.collection,
+        relation: value.relation,
+        ...(value.schema === undefined ? {} : { schema: value.schema }),
+        idColumn: value.idColumn,
+        select: "*",
+        filters: parseFilters(value.filters),
+        orders: parseOrders(value.orders),
+        limit: value.limit,
+        ...(value.identityScope === undefined ? {} : { identityScope: value.identityScope }),
+    };
+    if (!sameStrings([parsedBinding.relation], [binding.relation])
+        || parsedBinding.collection !== binding.collection
+        || parsedBinding.endpoint !== binding.endpoint) {
+        throw new PostgrestCursorError("foreign");
+    }
+    if (!sameBinding(parsedBinding, binding))
+        throw new PostgrestCursorError("changed-query");
+    return {
+        page: value.page,
+        values: parseValues(value.values, binding.orders.length),
+    };
+}
+/**
+ * Builds the PostgREST `or` expression for keyset continuation after one row.
+ *
+ * PostgREST/PostgreSQL defaults are used: `asc` sorts nulls last and `desc`
+ * sorts nulls first. The caller must append the configured primary key as a
+ * final non-null tie-breaker; this function relies on that final key to make a
+ * continuation expressible even when a user order column is null.
+ */
+export function postgrestKeysetFilter(orders, values) {
+    if (orders.length === 0 || values.length !== orders.length) {
+        throw new PostgrestCursorError("malformed");
+    }
+    const terms = [];
+    for (let index = 0; index < orders.length; index += 1) {
+        const order = orders[index];
+        const value = values[index];
+        if (order === undefined || value === undefined)
+            throw new PostgrestCursorError("malformed");
+        const field = postgrestFieldKey(order.field);
+        const prefix = orders.slice(0, index).map((item, prefixIndex) => {
+            const prefixValue = values[prefixIndex];
+            if (prefixValue === undefined)
+                throw new PostgrestCursorError("malformed");
+            return equality(item, prefixValue);
+        });
+        const nullsLast = order.direction === "asc";
+        const after = [];
+        if (value === null) {
+            if (!nullsLast)
+                after.push(`${field}.not.is.null`);
+        }
+        else {
+            after.push(`${field}.${order.direction === "asc" ? "gt" : "lt"}.${scalar(value)}`);
+            // The final order key is the non-null primary-key tie-breaker, so a
+            // null branch would only add a term that can never match.
+            if (nullsLast && index < orders.length - 1)
+                after.push(`${field}.is.null`);
+        }
+        for (const condition of after) {
+            const term = [...prefix, condition];
+            terms.push(term.length === 1 ? condition : `and(${term.join(",")})`);
+        }
+    }
+    if (terms.length === 0)
+        throw new PostgrestCursorError("malformed");
+    return `(${terms.join(",")})`;
+}
+//# sourceMappingURL=cursor.js.map

package/dist/cursor.js.map

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

package/dist/database.d.ts

@@ -0,0 +1,95 @@
+import { Key, type Codec, type Database, type QueryPage, type ReadwriteTransaction, type RecordSnapshot, type StructuredQuery, type UpdateData, type WriteSession } from "@dalgo/core";
+import { type PostgrestConnectionStatus, type PostgrestDiscovery } from "./discovery.js";
+export type PostgrestFetch = typeof globalThis.fetch;
+export type PostgrestHeaders = Readonly<Record<string, string>>;
+export type PostgrestHeaderProvider = PostgrestHeaders | (() => PostgrestHeaders | Promise<PostgrestHeaders>);
+export interface PostgrestDatabaseOptions {
+    /** PostgREST API root, normally the configured server origin or a proxy subpath. */
+    readonly baseUrl: string;
+    /**
+     * Allows plain HTTP only for `localhost`, `127.0.0.1` or `[::1]`. HTTPS is
+     * the default and remains the only option for every hosted origin.
+     */
+    readonly allowInsecureLoopbackHttp?: boolean;
+    /** PostgREST schema/profile selected with `Accept-Profile`/`Content-Profile`. */
+    readonly schema?: string;
+    /** Alias for `schema`; supplying both must resolve to the same profile. */
+    readonly profile?: string;
+    /** Name of the primary-key column shared by exposed adapter relations. Defaults to `id`. */
+    readonly idColumn?: string;
+    /** Maps a top-level DALgo collection name to an exposed PostgREST relation. */
+    readonly relationName?: (collection: string) => string;
+    /** Re-evaluated for every request; use it for refreshed Bearer or cookie headers. */
+    readonly headers?: PostgrestHeaderProvider;
+    /**
+     * Optional stable, non-secret tenant/user/workspace identity. It is bound
+     * into opaque cursors so a cursor cannot be replayed under another role
+     * scope. Never put a token or password here.
+     */
+    readonly identityScope?: string;
+    readonly fetch?: PostgrestFetch;
+    readonly timeoutMs?: number;
+    readonly maxRequestBytes?: number;
+    readonly maxResponseBytes?: number;
+    readonly maxGetManyKeys?: number;
+    readonly maxParallelReads?: number;
+    readonly maxQueryLimit?: number;
+    readonly maxQueryOffset?: number;
+    readonly maxQueryPages?: number;
+    readonly maxDiscoveryRelations?: number;
+    readonly maxDiscoveryFieldsPerRelation?: number;
+    readonly maxDiscoveryBytes?: number;
+    readonly maxCursorBytes?: number;
+    readonly maxSchemaDepth?: number;
+}
+/** Deliberately excludes PostgREST/PostgreSQL error bodies, which can contain row values. */
+export declare class PostgrestHttpError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/** A redacted failure while obtaining headers, following a request, or consuming a response. */
+export declare class PostgrestRequestError extends Error {
+    constructor();
+}
+export declare class PostgrestDatabase implements Database, WriteSession {
+    #private;
+    constructor(options: PostgrestDatabaseOptions);
+    get<T>(key: Key, codec?: Codec<T>): Promise<RecordSnapshot<T>>;
+    getMany<T>(keys: readonly Key[], codec?: Codec<T>): Promise<readonly RecordSnapshot<T>[]>;
+    insert<T>(key: Key, data: T, codec?: Codec<T>): Promise<void>;
+    set<T>(key: Key, data: T, codec?: Codec<T>): Promise<void>;
+    update(key: Key, data: UpdateData): Promise<void>;
+    delete(key: Key): Promise<void>;
+    query<T>(query: StructuredQuery<T>): Promise<QueryPage<T>>;
+    /**
+     * Cancellable query entry point with an optional adapter-owned keyset cursor.
+     * The caller signal covers header acquisition, fetch and response-body
+     * reading, and shares one deadline with `query`.
+     */
+    queryWithSignal<T>(query: StructuredQuery<T>, signal: AbortSignal): Promise<QueryPage<T>>;
+    private queryPage;
+    private prepareQuery;
+    private cursorOrders;
+    private legacyOrders;
+    private cursorBinding;
+    /** Read-only provider metadata. It never calls an administration endpoint. */
+    discover(signal?: AbortSignal): Promise<PostgrestDiscovery>;
+    /** A safe UI-factory preflight: proves transport, headers and metadata access. */
+    testConnection(signal?: AbortSignal): Promise<PostgrestConnectionStatus>;
+    private get discoveryBounds();
+    private discoveryUnavailable;
+    private readonly metadataBody;
+    runReadwriteTransaction<Result>(callback: (transaction: ReadwriteTransaction) => Promise<Result>): Promise<Result>;
+    private relationUrl;
+    private relationForCollection;
+    private relationUrlForCollection;
+    private keyUrl;
+    private payload;
+    private writeHeaders;
+    private profileHeaders;
+    private readonly discard;
+    private request;
+    private rows;
+    private assertExactlyOne;
+    private record;
+}