@form-engine-ts/storage-postgres 2.3.0 → 2.5.1

package/README.md

@@ -28,3 +28,7 @@ const submissions = await storage.listSubmissions(schema.id, schema.version, {
 `client` may be a `Pool`, `Client`, or a wrapper exposing the same `query(text, values)` shape. The caller owns connections and transactions. `autoMigrate` defaults to `false`; when enabled, the adapter lazily runs idempotent `CREATE TABLE/INDEX IF NOT EXISTS` statements once before its first operation. Use a migration framework for production schema evolution.
 
 Schemas use a `(form_id, form_version)` primary key and JSONB payload. Responses use their globally unique ID as the primary key, retain searchable form/version/locale/timestamp columns, and store the complete submission as JSONB. Custom table names must be safe SQL identifiers. Range boundaries are inclusive and results are ordered by submission time and then ID. Schema deletion never cascades to responses; `clearResponses(formId)` removes every version of one form, while `clear()` deletes rows only from the configured tables.
+
+`listSubmissionPage(formId, { version, pageSize, cursor, since, until, locale })` uses a parameterized keyset query over
+`submitted_at, response_id`. Its opaque cursor handles equal timestamps without `OFFSET` gaps or duplicates.
+`metadataFilters` and custom `filter` predicates are applied before page sizing.

package/dist/index.cjs

@@ -182,6 +182,54 @@ function createPostgresStorage(options) {
       );
       return result.rows.map(parseSubmissionRow);
     },
+    async listSubmissionPage(formId, queryOptions = {}) {
+      await ensureReady();
+      const pageSize = (0, import_core.normalizeSubmissionPageSize)(queryOptions.pageSize);
+      const cursor = queryOptions.cursor === void 0 ? void 0 : (0, import_core.decodeSubmissionCursor)(queryOptions.cursor);
+      const conditions = ["form_id = $1"];
+      const params = [formId];
+      if (queryOptions.version !== void 0) {
+        params.push(queryOptions.version);
+        conditions.push(`form_version = $${params.length}`);
+      }
+      if (queryOptions.since !== void 0) {
+        params.push(queryOptions.since);
+        conditions.push(`submitted_at >= $${params.length}::timestamptz`);
+      }
+      if (queryOptions.until !== void 0) {
+        params.push(queryOptions.until);
+        conditions.push(`submitted_at <= $${params.length}::timestamptz`);
+      }
+      if (queryOptions.locale !== void 0) {
+        params.push(queryOptions.locale);
+        conditions.push(`locale = $${params.length}`);
+      }
+      if (cursor !== void 0) {
+        params.push(cursor.submittedAt);
+        const timestampParameter = params.length;
+        params.push(cursor.responseId);
+        conditions.push(
+          `(submitted_at > $${timestampParameter}::timestamptz OR (submitted_at = $${timestampParameter}::timestamptz AND response_id > $${params.length}))`
+        );
+      }
+      const requiresClientFiltering = queryOptions.filter !== void 0 || queryOptions.metadataFilters !== void 0;
+      if (!requiresClientFiltering) params.push(pageSize + 1);
+      const result = await options.client.query(
+        `SELECT response_id, form_id, form_version, locale, submitted_at, submission_json
+         FROM ${responsesTable} WHERE ${conditions.join(" AND ")}
+         ORDER BY submitted_at, response_id${requiresClientFiltering ? "" : ` LIMIT $${params.length}`}`,
+        params
+      );
+      const candidates = result.rows.map(parseSubmissionRow).filter((item) => (0, import_core.matchesSubmissionPageFilters)(item, queryOptions));
+      const hasMore = candidates.length > pageSize;
+      const items = candidates.slice(0, pageSize);
+      const last = items.at(-1);
+      return {
+        items,
+        hasMore,
+        ...hasMore && last !== void 0 ? { nextCursor: (0, import_core.encodeSubmissionCursor)({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
+      };
+    },
     async deleteSubmission(submissionId) {
       await ensureReady();
       await options.client.query(`DELETE FROM ${responsesTable} WHERE response_id = $1`, [submissionId]);

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { FormStorageAdapter } from '@form-engine-ts/core';
+import { PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
 
 interface PostgresClientLike {
     query(text: string, params?: unknown[]): Promise<{
@@ -11,6 +11,6 @@ interface PostgresStorageOptions {
     readonly responsesTable?: string;
     readonly autoMigrate?: boolean;
 }
-declare function createPostgresStorage(options: PostgresStorageOptions): FormStorageAdapter;
+declare function createPostgresStorage(options: PostgresStorageOptions): PagedSubmissionStorageAdapter;
 
 export { type PostgresClientLike, type PostgresStorageOptions, createPostgresStorage };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FormStorageAdapter } from '@form-engine-ts/core';
+import { PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
 
 interface PostgresClientLike {
     query(text: string, params?: unknown[]): Promise<{
@@ -11,6 +11,6 @@ interface PostgresStorageOptions {
     readonly responsesTable?: string;
     readonly autoMigrate?: boolean;
 }
-declare function createPostgresStorage(options: PostgresStorageOptions): FormStorageAdapter;
+declare function createPostgresStorage(options: PostgresStorageOptions): PagedSubmissionStorageAdapter;
 
 export { type PostgresClientLike, type PostgresStorageOptions, createPostgresStorage };

package/dist/index.js

@@ -1,5 +1,11 @@
 // src/index.ts
-import { assertValidFormSchema } from "@form-engine-ts/core";
+import {
+  assertValidFormSchema,
+  decodeSubmissionCursor,
+  encodeSubmissionCursor,
+  matchesSubmissionPageFilters,
+  normalizeSubmissionPageSize
+} from "@form-engine-ts/core";
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -158,6 +164,54 @@ function createPostgresStorage(options) {
       );
       return result.rows.map(parseSubmissionRow);
     },
+    async listSubmissionPage(formId, queryOptions = {}) {
+      await ensureReady();
+      const pageSize = normalizeSubmissionPageSize(queryOptions.pageSize);
+      const cursor = queryOptions.cursor === void 0 ? void 0 : decodeSubmissionCursor(queryOptions.cursor);
+      const conditions = ["form_id = $1"];
+      const params = [formId];
+      if (queryOptions.version !== void 0) {
+        params.push(queryOptions.version);
+        conditions.push(`form_version = $${params.length}`);
+      }
+      if (queryOptions.since !== void 0) {
+        params.push(queryOptions.since);
+        conditions.push(`submitted_at >= $${params.length}::timestamptz`);
+      }
+      if (queryOptions.until !== void 0) {
+        params.push(queryOptions.until);
+        conditions.push(`submitted_at <= $${params.length}::timestamptz`);
+      }
+      if (queryOptions.locale !== void 0) {
+        params.push(queryOptions.locale);
+        conditions.push(`locale = $${params.length}`);
+      }
+      if (cursor !== void 0) {
+        params.push(cursor.submittedAt);
+        const timestampParameter = params.length;
+        params.push(cursor.responseId);
+        conditions.push(
+          `(submitted_at > $${timestampParameter}::timestamptz OR (submitted_at = $${timestampParameter}::timestamptz AND response_id > $${params.length}))`
+        );
+      }
+      const requiresClientFiltering = queryOptions.filter !== void 0 || queryOptions.metadataFilters !== void 0;
+      if (!requiresClientFiltering) params.push(pageSize + 1);
+      const result = await options.client.query(
+        `SELECT response_id, form_id, form_version, locale, submitted_at, submission_json
+         FROM ${responsesTable} WHERE ${conditions.join(" AND ")}
+         ORDER BY submitted_at, response_id${requiresClientFiltering ? "" : ` LIMIT $${params.length}`}`,
+        params
+      );
+      const candidates = result.rows.map(parseSubmissionRow).filter((item) => matchesSubmissionPageFilters(item, queryOptions));
+      const hasMore = candidates.length > pageSize;
+      const items = candidates.slice(0, pageSize);
+      const last = items.at(-1);
+      return {
+        items,
+        hasMore,
+        ...hasMore && last !== void 0 ? { nextCursor: encodeSubmissionCursor({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
+      };
+    },
     async deleteSubmission(submissionId) {
       await ensureReady();
       await options.client.query(`DELETE FROM ${responsesTable} WHERE response_id = $1`, [submissionId]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/storage-postgres",
-  "version": "2.3.0",
+  "version": "2.5.1",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.3.0"
+    "@form-engine-ts/core": "2.5.1"
   },
   "peerDependencies": {
     "pg": "^8.11.0"