@oliphaunt/wasix-ts 0.1.0

package/lib/database-root.js

@@ -0,0 +1,139 @@
+import { PHYSICAL_FORMAT as CARRIER_PHYSICAL_FORMAT, POSTGRES_MAJOR as CARRIER_POSTGRES_MAJOR, } from '@oliphaunt/liboliphaunt-wasix';
+export const DATABASE_ROOT_DESCRIPTOR = '.oliphaunt.json';
+export const DATABASE_ROOT_SCHEMA = 'oliphaunt-database-root-v1';
+export const DATABASE_ROOT_PGDATA = 'pgdata';
+export const DATABASE_ROOT_POSTGRES_MAJOR = CARRIER_POSTGRES_MAJOR;
+export const WASIX_PHYSICAL_FORMAT = CARRIER_PHYSICAL_FORMAT;
+export const NATIVE_PHYSICAL_FORMAT = 'native-pg18-v1';
+export function wasixDatabaseRootDescriptor() {
+    return {
+        schema: DATABASE_ROOT_SCHEMA,
+        engineFamily: 'wasix',
+        pgdata: DATABASE_ROOT_PGDATA,
+        postgresMajor: DATABASE_ROOT_POSTGRES_MAJOR,
+        physicalFormat: WASIX_PHYSICAL_FORMAT,
+    };
+}
+export function parseDatabaseRootDescriptor(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const descriptor = value;
+    const keys = Object.keys(descriptor).sort();
+    if (keys.length !== 5 ||
+        keys[0] !== 'engineFamily' ||
+        keys[1] !== 'pgdata' ||
+        keys[2] !== 'physicalFormat' ||
+        keys[3] !== 'postgresMajor' ||
+        keys[4] !== 'schema') {
+        return undefined;
+    }
+    if (descriptor.schema !== DATABASE_ROOT_SCHEMA ||
+        (descriptor.engineFamily !== 'native' && descriptor.engineFamily !== 'wasix') ||
+        descriptor.pgdata !== DATABASE_ROOT_PGDATA ||
+        descriptor.postgresMajor !== DATABASE_ROOT_POSTGRES_MAJOR ||
+        (descriptor.engineFamily === 'native'
+            ? descriptor.physicalFormat !== NATIVE_PHYSICAL_FORMAT
+            : descriptor.physicalFormat !== WASIX_PHYSICAL_FORMAT)) {
+        return undefined;
+    }
+    return descriptor;
+}
+/** Parse the root descriptor while rejecting duplicate JSON keys. */
+export function parseDatabaseRootDescriptorText(text) {
+    return parseDatabaseRootDescriptor(parseJsonWithUniqueObjectKeys(text));
+}
+/** Parse JSON while retaining the duplicate-key rejection lost by JSON.parse(). */
+export function parseJsonWithUniqueObjectKeys(text) {
+    try {
+        const value = JSON.parse(text);
+        const end = scanJsonValue(text, skipWhitespace(text, 0));
+        return end !== undefined && skipWhitespace(text, end) === text.length ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readJsonString(text, offset) {
+    if (text[offset] !== '"')
+        return undefined;
+    for (let index = offset + 1; index < text.length; index += 1) {
+        const character = text[index];
+        if (character === '\\') {
+            index += 1;
+            continue;
+        }
+        if (character === '"') {
+            const value = JSON.parse(text.slice(offset, index + 1));
+            return typeof value === 'string' ? { value, next: index + 1 } : undefined;
+        }
+    }
+    return undefined;
+}
+function scanJsonValue(text, offset) {
+    if (text[offset] === '"')
+        return readJsonString(text, offset)?.next;
+    if (text[offset] === '{')
+        return scanJsonObject(text, offset);
+    if (text[offset] === '[')
+        return scanJsonArray(text, offset);
+    let end = offset;
+    while (end < text.length &&
+        text[end] !== ',' &&
+        text[end] !== '}' &&
+        text[end] !== ']' &&
+        !isJsonWhitespace(text[end])) {
+        end += 1;
+    }
+    return end > offset ? end : undefined;
+}
+function scanJsonObject(text, offset) {
+    let next = skipWhitespace(text, offset + 1);
+    if (text[next] === '}')
+        return next + 1;
+    const keys = new Set();
+    while (next < text.length) {
+        const key = readJsonString(text, next);
+        if (key === undefined || keys.has(key.value))
+            return undefined;
+        keys.add(key.value);
+        next = skipWhitespace(text, key.next);
+        if (text[next] !== ':')
+            return undefined;
+        const valueEnd = scanJsonValue(text, skipWhitespace(text, next + 1));
+        if (valueEnd === undefined)
+            return undefined;
+        next = skipWhitespace(text, valueEnd);
+        if (text[next] === '}')
+            return next + 1;
+        if (text[next] !== ',')
+            return undefined;
+        next = skipWhitespace(text, next + 1);
+    }
+    return undefined;
+}
+function scanJsonArray(text, offset) {
+    let next = skipWhitespace(text, offset + 1);
+    if (text[next] === ']')
+        return next + 1;
+    while (next < text.length) {
+        const valueEnd = scanJsonValue(text, next);
+        if (valueEnd === undefined)
+            return undefined;
+        next = skipWhitespace(text, valueEnd);
+        if (text[next] === ']')
+            return next + 1;
+        if (text[next] !== ',')
+            return undefined;
+        next = skipWhitespace(text, next + 1);
+    }
+    return undefined;
+}
+function skipWhitespace(text, offset) {
+    while (offset < text.length && isJsonWhitespace(text[offset])) {
+        offset += 1;
+    }
+    return offset;
+}
+function isJsonWhitespace(character) {
+    return character === ' ' || character === '\t' || character === '\n' || character === '\r';
+}

package/lib/database.d.ts

@@ -0,0 +1,135 @@
+import { type CommandResult, type DescribeResult, type ExecResult, type InferQueryRow, type ParameterOptions, type QueryParam, type QueryOptions, type QueryResult, type RawQueryResult } from './query.js';
+import type { WasixStorageSyncBoundary } from './storage-provider.js';
+import type { WasixProtocolConnection } from './pgwire-connection.js';
+import type { WasixPgDumpProcessOptions, WasixToolProcessOptions, WasixToolProcessResult } from './tool-runtime.js';
+import type { BinaryInput, OliphauntDatabase, OliphauntTransaction, ProtocolChunkCallback } from './types.js';
+/** @internal Buffered protocol fallbacks use the same observable callback granularity. */
+export declare const WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES: number;
+type QueryReadOptions = Omit<QueryOptions, 'encoders'>;
+/** @internal Publish a promise before starting reentrant ownership teardown. */
+export declare function createWasixDeferred<T>(): Readonly<{
+    promise: Promise<T>;
+    resolve(value: T | PromiseLike<T>): void;
+    reject(error: unknown): void;
+}>;
+export type WasixDatabaseIdentity = Readonly<{
+    username: string;
+    database: string;
+}>;
+export type WasixDatabaseResource = Readonly<{
+    close(): void | Promise<void>;
+}>;
+/** @internal Observable ownership loss for execution sessions with a fallible transport. */
+export type WasixDatabaseSessionTerminalState = Readonly<{
+    /** True only after the execution owner has terminated unexpectedly. */
+    readonly terminal: boolean;
+    /** The first transport failure that made the execution owner terminal. */
+    readonly failure: Error | undefined;
+}>;
+/** @internal Validate the explicit PostgreSQL startup identity once at open. */
+export declare function normalizeWasixDatabaseIdentity(username: string, database: string): WasixDatabaseIdentity;
+/** @internal Host-publication policy for one pgwire exchange. */
+export type WasixPersistenceMode = 'sync' | 'defer';
+export type WasixProtocolConnectionMode = 'server' | 'tool';
+/** @internal Whether a stream completed normally or recovered after stopping callback delivery. */
+export type WasixProtocolStreamOutcome = 'complete' | 'callbackAborted';
+/** @internal A database FIFO slot whose guest connection starts explicitly. */
+export type WasixProtocolConnectionReservation = Readonly<{
+    start(): Promise<void>;
+    cancel(): void;
+}>;
+/** @internal Execution seam shared by caller- and package-owned database handles. */
+export type WasixDatabaseSession = {
+    /** The session can safely block away from its public caller while serving a connection. */
+    readonly supportsProtocolConnections?: boolean;
+    readonly identity?: WasixDatabaseIdentity;
+    /** Optional shared state for an execution owner that can die independently of the handle. */
+    readonly terminalState?: WasixDatabaseSessionTerminalState;
+    exec(input: Uint8Array, persistence?: WasixPersistenceMode): Promise<Uint8Array>;
+    execStream?(input: Uint8Array, onChunk: ProtocolChunkCallback, persistence?: WasixPersistenceMode): Promise<WasixProtocolStreamOutcome>;
+    sync(boundary: WasixStorageSyncBoundary): Promise<void>;
+    /** Internal test seams may omit backup; production sessions always provide it. */
+    backup?(): Promise<Uint8Array>;
+    runPgDump?(options: WasixPgDumpProcessOptions): Promise<WasixToolProcessResult>;
+    /** Internal Node-compatible native path for both packaged frontend tools. */
+    runTool?(options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;
+    serve?(connection: WasixProtocolConnection, mode: WasixProtocolConnectionMode): Promise<void>;
+    /**
+     * Begin the session's one terminal teardown attempt.
+     *
+     * Implementations must stop admitting work immediately, return the same
+     * promise to every later caller, and remain terminal even when teardown
+     * rejects after owned transport or host resources have been destroyed.
+     */
+    close(): Promise<void>;
+    /** Force-stop an SDK-owned execution lane when orderly shutdown stalls. */
+    abort?(): void | Promise<void>;
+};
+type ForgottenDatabaseGeneration = Readonly<Record<never, never>>;
+type FinalizationRegistryLike = Readonly<{
+    register(target: object, heldValue: ForgottenDatabaseGeneration, unregisterToken: object): void;
+    unregister(unregisterToken: object): boolean;
+}>;
+type FinalizationRegistryFactory = (cleanup: (generation: ForgottenDatabaseGeneration) => void) => FinalizationRegistryLike;
+export type WasixForgottenDatabaseRegistration = Readonly<{
+    generation: ForgottenDatabaseGeneration;
+}>;
+/**
+ * Tracks only session owners, never their public database handles.
+ *
+ * The finalizer's held value is an opaque generation token. The session lives
+ * in a separately keyed table, so an already queued finalizer can atomically
+ * prove that it still owns the exact registration before scheduling cleanup.
+ *
+ * @internal
+ */
+export declare class WasixForgottenDatabaseRegistry {
+    #private;
+    constructor(createRegistry?: FinalizationRegistryFactory, schedule?: (work: () => void) => void);
+    register(owner: object, session: WasixDatabaseSession): WasixForgottenDatabaseRegistration;
+    unregister(registration: WasixForgottenDatabaseRegistration): void;
+}
+/** @internal Public database state machine; construction stays behind Oliphaunt.open(). */
+export declare class WasixDatabaseImpl implements OliphauntDatabase {
+    #private;
+    constructor(session: WasixDatabaseSession, forgottenRegistry?: WasixForgottenDatabaseRegistry | undefined);
+    get closed(): boolean;
+    execute(sql: string, parameters?: ReadonlyArray<QueryParam>, options?: ParameterOptions): Promise<CommandResult>;
+    query<Row = never, const Options extends QueryOptions = {}>(sql: string, parameters?: ReadonlyArray<QueryParam>, options?: Options & QueryOptions): Promise<QueryResult<InferQueryRow<Options, Row>>>;
+    queryRaw(sql: string, parameters?: ReadonlyArray<QueryParam>, options?: ParameterOptions): Promise<RawQueryResult>;
+    exec<Row = never, const Options extends QueryReadOptions = {}>(sql: string, options?: Options & QueryReadOptions): Promise<ExecResult<InferQueryRow<Options, Row>>>;
+    describe(sql: string, parameterTypeOids?: ReadonlyArray<number>): Promise<DescribeResult>;
+    execProtocolRaw(input: BinaryInput): Promise<Uint8Array>;
+    execProtocolRawStream(input: BinaryInput, onChunk: ProtocolChunkCallback): Promise<void>;
+    backup(): Promise<Uint8Array>;
+    /** @internal Run pg_dump in the database-owning execution realm without another transport. */
+    runPgDump(options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;
+    /** @internal Run a packaged tool without the legacy Wasmer tool worker. */
+    runNativeTool(options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;
+    /** @internal Serialized connection ownership used by optional server/tool packages. */
+    runProtocolConnection(connection: WasixProtocolConnection, mode: WasixProtocolConnectionMode): Promise<void>;
+    /** @internal Reserve call order without entering the guest before a client is ready. */
+    reserveProtocolConnection(connection: WasixProtocolConnection, mode: WasixProtocolConnectionMode): WasixProtocolConnectionReservation;
+    transaction<T>(body: (transaction: OliphauntTransaction) => Promise<T> | T): Promise<T>;
+    close(): Promise<void>;
+    /** @internal Register package-owned state that must not outlive this database. */
+    registerResource(resource: WasixDatabaseResource): void;
+    /** @internal Identity used by private protocol clients such as pg_dump and psql. */
+    get identity(): WasixDatabaseIdentity;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** @internal Optional packages acquire exclusive ownership without expanding the public class. */
+export declare function runWasixProtocolConnection(database: OliphauntDatabase, connection: WasixProtocolConnection, mode: WasixProtocolConnectionMode): Promise<void>;
+/** @internal Execute pg_dump in the realm that owns this database. */
+export declare function runWasixPgDumpProcess(database: OliphauntDatabase, options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;
+/** @internal Return undefined only when this realm uses the browser Wasmer backend. */
+export declare function tryRunWasixNativeToolProcess(database: OliphauntDatabase, options: WasixToolProcessOptions): Promise<WasixToolProcessResult> | undefined;
+/** @internal Reserve a Worker-owned connection in the database FIFO. */
+export declare function reserveWasixProtocolConnection(database: OliphauntDatabase, connection: WasixProtocolConnection, mode: WasixProtocolConnectionMode): WasixProtocolConnectionReservation;
+/** @internal Fail before loading a tool or opening a listener for unsupported placement. */
+export declare function assertWasixProtocolConnectionTarget(database: OliphauntDatabase): asserts database is WasixDatabaseImpl;
+/** @internal Attach an optional-package resource without adding public database methods. */
+export declare function registerWasixDatabaseResource(database: OliphauntDatabase, resource: WasixDatabaseResource): void;
+/** @internal Return the exact startup identity owned by a WASIX database handle. */
+export declare function getWasixDatabaseIdentity(database: OliphauntDatabase): WasixDatabaseIdentity;
+export {};