@typed-sql/postgres 1.0.0-beta.2 → 1.0.0

package/dist/packages/postgres/src/stream.d.ts

@@ -0,0 +1,34 @@
+import type { QueryStream } from "@typed-sql/core";
+export interface PostgresCursorLike {
+    read(rowCount: number): Promise<readonly Record<string, unknown>[]>;
+    close(): Promise<void>;
+}
+export interface PostgresCursorLease {
+    readonly cursor: PostgresCursorLike;
+    release?(cleanupError?: unknown): void | Promise<void>;
+}
+export interface PostgresQueryStreamOptions {
+    readonly batchSize: number;
+    readonly start: () => Promise<PostgresCursorLease>;
+    readonly onError?: (error: unknown) => void;
+    readonly onStart?: () => void;
+    readonly onClose?: () => void;
+}
+/**
+ * A demand-driven row iterator over a cursor lease.
+ *
+ * Operations are serialized because native PostgreSQL cursors cannot safely process overlapping
+ * reads. Cleanup always attempts both cursor close and lease release, while keeping the first
+ * operation or cleanup error as the observable failure.
+ */
+export declare class PostgresQueryStream<Row> implements QueryStream<Row> {
+    #private;
+    constructor(options: PostgresQueryStreamOptions);
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<Row, undefined>>;
+    return(): Promise<IteratorResult<Row, undefined>>;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare function validatePostgresStreamBatchSize(batchSize: number | undefined): number;
+//# sourceMappingURL=stream.d.ts.map

package/dist/packages/postgres/src/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../../src/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,OAAO,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAMD;;;;;;GAMG;AACH,qBAAa,mBAAmB,CAAC,GAAG,CAAE,YAAW,WAAW,CAAC,GAAG,CAAC;;IAY/D,YAAY,OAAO,EAAE,0BAA0B,EAM9C;IAED,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,IAAI,CAE7B;IAED,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAuB9C;IAED,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAKhD;IAED,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;CA8CF;AAED,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMrF"}

package/dist/packages/postgres/src/stream.js

@@ -0,0 +1,124 @@
+function done() {
+    return { done: true, value: undefined };
+}
+/**
+ * A demand-driven row iterator over a cursor lease.
+ *
+ * Operations are serialized because native PostgreSQL cursors cannot safely process overlapping
+ * reads. Cleanup always attempts both cursor close and lease release, while keeping the first
+ * operation or cleanup error as the observable failure.
+ */
+export class PostgresQueryStream {
+    #batchSize;
+    #start;
+    #onClose;
+    #onError;
+    #onStart;
+    #buffer = [];
+    #bufferIndex = 0;
+    #lease;
+    #operation = Promise.resolve();
+    #terminal = false;
+    constructor(options) {
+        this.#batchSize = options.batchSize;
+        this.#start = options.start;
+        this.#onStart = options.onStart;
+        this.#onClose = options.onClose;
+        this.#onError = options.onError;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    next() {
+        return this.#enqueue(async () => {
+            if (this.#terminal)
+                return done();
+            if (this.#bufferIndex < this.#buffer.length) {
+                return { done: false, value: this.#buffer[this.#bufferIndex++] };
+            }
+            try {
+                if (this.#lease === undefined)
+                    this.#onStart?.();
+                this.#lease ??= await this.#start();
+                const rows = await this.#lease.cursor.read(this.#batchSize);
+                if (rows.length === 0) {
+                    await this.#terminate();
+                    return done();
+                }
+                this.#buffer = rows;
+                this.#bufferIndex = 1;
+                return { done: false, value: this.#buffer[0] };
+            }
+            catch (error) {
+                await this.#terminate(error);
+                throw error;
+            }
+        });
+    }
+    return() {
+        return this.#enqueue(async () => {
+            await this.#terminate();
+            return done();
+        });
+    }
+    close() {
+        return this.#enqueue(() => this.#terminate());
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    #enqueue(operation) {
+        const result = this.#operation.then(operation);
+        this.#operation = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async #terminate(primaryError) {
+        if (this.#terminal) {
+            if (primaryError !== undefined)
+                throw primaryError;
+            return;
+        }
+        this.#terminal = true;
+        const hadLease = this.#lease !== undefined;
+        this.#buffer = [];
+        this.#bufferIndex = 0;
+        let cleanupError;
+        try {
+            if (this.#lease !== undefined)
+                await this.#lease.cursor.close();
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+        try {
+            await this.#lease?.release?.(primaryError !== undefined ? primaryError : cleanupError);
+        }
+        catch (error) {
+            cleanupError ??= error;
+        }
+        finally {
+            this.#onClose?.();
+        }
+        const terminalError = primaryError ?? cleanupError;
+        if (hadLease && terminalError !== undefined) {
+            try {
+                this.#onError?.(terminalError);
+            }
+            catch {
+                /* Lifecycle observers cannot replace the stream's primary error. */
+            }
+        }
+        if (primaryError !== undefined)
+            throw primaryError;
+        if (cleanupError !== undefined)
+            throw cleanupError;
+    }
+}
+export function validatePostgresStreamBatchSize(batchSize) {
+    const resolved = batchSize ?? 100;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new RangeError("PostgreSQL stream batchSize must be a positive safe integer");
+    }
+    return resolved;
+}
+//# sourceMappingURL=stream.js.map

package/dist/packages/postgres/src/stream.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typed-sql/postgres",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0",
   "description": "PostgreSQL grammar, schema introspection, type resolution, and driver-neutral runtime codecs for typed-sql.",
   "license": "MIT",
   "author": "Lojhan",
@@ -39,9 +39,9 @@
   },
   "dependencies": {
     "@types/pg": "8.23.1",
-    "@typed-sql/ast": "1.0.0-beta.2",
-    "@typed-sql/schema": "1.0.0-beta.2",
-    "@typed-sql/core": "1.0.0-beta.2"
+    "@typed-sql/ast": "1.0.0",
+    "@typed-sql/core": "1.0.0",
+    "@typed-sql/schema": "1.0.0"
   },
   "scripts": {
     "test": "poku test --reporter=compact --enforce",