@byline/db-postgres 2.1.2 → 2.2.0

package/dist/database/schema/index.js

@@ -7,6 +7,7 @@
  */
 import { eq, relations, sql } from 'drizzle-orm';
 import { bigint, boolean, customType, date, decimal, index, integer, jsonb, pgTable, pgView, real, text, time, timestamp, unique, uuid, varchar, } from 'drizzle-orm/pg-core';
+import { createdAt, timestamps } from './common.js';
 /**
  * `varchar(...)` with explicit byte-wise (C) collation.
  *
@@ -44,8 +45,7 @@ export const collections = pgTable('byline_collections', {
     // `ensureCollections()` run post-migration, tightens to NOT NULL when
     // the `collection_versions` history table lands.
     schema_hash: varchar('schema_hash', { length: 64 }),
-    created_at: timestamp('created_at').defaultNow(),
-    updated_at: timestamp('updated_at').defaultNow(),
+    ...timestamps,
 });
 // Documents table
 export const documents = pgTable('byline_documents', {
@@ -63,8 +63,7 @@ export const documents = pgTable('byline_documents', {
     // comparison — the fractional-index algorithm requires this. See
     // `varcharByteSorted` above and docs/COLLECTIONS.md (Orderable collections).
     order_key: varcharByteSorted('order_key', { length: 128 }),
-    created_at: timestamp('created_at').defaultNow(),
-    updated_at: timestamp('updated_at').defaultNow(),
+    ...timestamps,
 }, (table) => [
     index('idx_documents_collection').on(table.collection_id),
     index('idx_documents_collection_order').on(table.collection_id, table.order_key),
@@ -87,8 +86,7 @@ export const documentVersions = pgTable('byline_document_versions', {
     event_type: varchar('event_type', { length: 20 }).notNull().default('create'), // 'create', 'update', 'delete'
     status: varchar('status', { length: 50 }).default('draft'),
     is_deleted: boolean('is_deleted').default(false), // Tombstone for soft deletes
-    created_at: timestamp('created_at').defaultNow(),
-    updated_at: timestamp('updated_at').defaultNow(),
+    ...timestamps,
     created_by: uuid('created_by'),
     change_summary: text('change_summary'),
 }, (table) => [
@@ -121,8 +119,7 @@ export const documentPaths = pgTable('byline_document_paths', {
         .notNull()
         .references(() => collections.id, { onDelete: 'cascade' }),
     path: varchar('path', { length: 255 }).notNull(),
-    created_at: timestamp('created_at').defaultNow(),
-    updated_at: timestamp('updated_at').defaultNow(),
+    ...timestamps,
 }, (table) => [
     // One path per (logical document, locale).
     unique('unique_document_paths_document_locale').on(table.document_id, table.locale),
@@ -142,7 +139,7 @@ export const documentRelationships = pgTable('byline_document_relationships', {
     child_document_id: uuid('child_document_id')
         .notNull()
         .references(() => documents.id, { onDelete: 'cascade' }),
-    created_at: timestamp('created_at').defaultNow(),
+    ...createdAt,
 }, (table) => [
     // Composite primary key to ensure a child is only parented once by the same parent.
     unique().on(table.parent_document_id, table.child_document_id),
@@ -258,8 +255,7 @@ const baseStoreColumns = {
     field_name: varchar('field_name', { length: 255 }).notNull(),
     locale: varchar('locale', { length: 10 }).notNull().default('default'),
     parent_path: varchar('parent_path', { length: 500 }),
-    created_at: timestamp('created_at').defaultNow(),
-    updated_at: timestamp('updated_at').defaultNow(),
+    ...timestamps,
 };
 // 1. TEXT FIELDS TABLE
 export const textStore = pgTable('byline_store_text', {
@@ -364,8 +360,7 @@ export const metaStore = pgTable('byline_store_meta', {
     // Optional opaque metadata payload for this node. Common attributes like
     // label, icon, collapsed state, etc. can be stored here.
     meta: jsonb('meta'),
-    created_at: timestamp('created_at').defaultNow(),
-    updated_at: timestamp('updated_at').defaultNow(),
+    ...timestamps,
 }, (table) => [
     // Fast lookup by document and node type/path when enriching reconstructed
     // trees with meta information.
@@ -431,6 +426,26 @@ export const jsonStore = pgTable('byline_store_json', {
     index('idx_json_keys').using('gin', table.object_keys),
     unique('unique_json_field').on(table.document_version_id, table.field_path, table.locale),
 ]);
+// ---------------------------------------------------------------------------
+// Counter groups registry
+// ---------------------------------------------------------------------------
+//
+// One row per counter `group` discovered in collection field definitions.
+// The actual ID allocator is a Postgres SEQUENCE (named in `sequence_name`),
+// reconciled at boot by `IDbAdapter.ensureCounterGroup`. The registry table
+// itself only records that the group exists and which sequence backs it —
+// it is not used in the hot allocation path (`nextval()` operates on the
+// sequence object directly).
+//
+// Why a separate table rather than reading sequences from
+// `information_schema`: the mapping from `group_name` → `sequence_name`
+// belongs in the application's schema, not in PG metadata, so backups and
+// adapter logic have a stable name to anchor against.
+export const counterGroups = pgTable('byline_counter_groups', {
+    group_name: text('group_name').primaryKey(),
+    sequence_name: text('sequence_name').notNull(),
+    ...createdAt,
+});
 // RELATIONS
 // =========
 export const collectionsRelations = relations(collections, ({ many }) => ({

package/dist/index.js

@@ -8,6 +8,7 @@
 import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './database/schema/index.js';
+import { createCounterCommands } from './modules/counters/counters-commands.js';
 import { createCommandBuilders } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
 export const pgAdapter = ({ connectionString, collections, defaultContentLocale, }) => {
@@ -20,8 +21,12 @@ export const pgAdapter = ({ connectionString, collections, defaultContentLocale,
     const db = drizzle(pool, { schema });
     const commandBuilders = createCommandBuilders(db, defaultContentLocale);
     const queryBuilders = createQueryBuilders(db, collections, defaultContentLocale);
+    const counterCommands = createCounterCommands(db);
     return {
-        commands: commandBuilders,
+        commands: {
+            ...commandBuilders,
+            counters: counterCommands,
+        },
         queries: queryBuilders,
         drizzle: db,
         pool,

package/dist/modules/counters/counters-commands.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { ICounterCommands } from '@byline/core';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../database/schema/index.js';
+type DatabaseConnection = NodePgDatabase<typeof schema>;
+export declare class CounterCommands implements ICounterCommands {
+    private db;
+    constructor(db: DatabaseConnection);
+    ensureCounterGroup(groupName: string): Promise<{
+        groupName: string;
+        sequenceName: string;
+    }>;
+    nextCounterValue(groupName: string): Promise<number>;
+}
+export declare function createCounterCommands(db: DatabaseConnection): ICounterCommands;
+export {};

package/dist/modules/counters/counters-commands.js

@@ -0,0 +1,96 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { createHash } from 'node:crypto';
+import { eq, sql } from 'drizzle-orm';
+import { counterGroups } from '../../database/schema/index.js';
+/**
+ * Derive a stable, safe Postgres identifier for the sequence backing a
+ * counter group.
+ *
+ * Two competing goals: humans browsing the database should be able to
+ * recognise which group a sequence belongs to, and the name must never
+ * collide for two different group strings. We satisfy both by combining
+ * a sanitised slug of the group name with an 8-character SHA-256 prefix
+ * — so `'library-facets'` becomes something like
+ * `byline_cseq_library_facets_8c2f4d6a`.
+ *
+ * Postgres identifier limit is 63 bytes (NAMEDATALEN-1). The prefix is
+ * 12 bytes, the hash + underscore is 9, leaving 42 bytes for the slug.
+ */
+function deriveSequenceName(groupName) {
+    const slug = groupName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 42);
+    const hash = createHash('sha256').update(groupName).digest('hex').slice(0, 8);
+    return slug ? `byline_cseq_${slug}_${hash}` : `byline_cseq_${hash}`;
+}
+export class CounterCommands {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async ensureCounterGroup(groupName) {
+        if (!groupName || typeof groupName !== 'string') {
+            throw new Error(`ensureCounterGroup: groupName must be a non-empty string`);
+        }
+        const sequenceName = deriveSequenceName(groupName);
+        // Two statements, both idempotent. We deliberately do not wrap them
+        // in a single transaction: CREATE SEQUENCE acquires its own catalog
+        // locks, and DDL inside a long-running INSERT can deadlock under
+        // concurrent boots. Splitting them keeps each step short.
+        //
+        // The sequence is created first so that even if the INSERT loses a
+        // race, the next caller's nextval() on the existing row's
+        // sequence_name still works.
+        await this.db.execute(sql.raw(`CREATE SEQUENCE IF NOT EXISTS "${sequenceName}" AS BIGINT`));
+        await this.db
+            .insert(counterGroups)
+            .values({ group_name: groupName, sequence_name: sequenceName })
+            .onConflictDoNothing({ target: counterGroups.group_name });
+        return { groupName, sequenceName };
+    }
+    async nextCounterValue(groupName) {
+        if (!groupName || typeof groupName !== 'string') {
+            throw new Error(`nextCounterValue: groupName must be a non-empty string`);
+        }
+        // Resolve the sequence name from the registry rather than re-deriving
+        // it. This keeps callers honest — if the group was never registered
+        // via ensureCounterGroup, we surface that immediately rather than
+        // silently creating a new sequence the first time a value is asked
+        // for (which would mask configuration bugs during boot).
+        const rows = await this.db
+            .select({ sequence_name: counterGroups.sequence_name })
+            .from(counterGroups)
+            .where(eq(counterGroups.group_name, groupName))
+            .limit(1);
+        if (rows.length === 0) {
+            throw new Error(`nextCounterValue: counter group "${groupName}" is not registered. ` +
+                `Call ensureCounterGroup at boot before any document create that uses it.`);
+        }
+        const sequenceName = rows[0].sequence_name;
+        // sql.raw is safe here: sequenceName came from our own registry row,
+        // which was written by ensureCounterGroup from deriveSequenceName
+        // — only [a-z0-9_] characters, no user-controlled SQL.
+        const result = await this.db.execute(sql.raw(`SELECT nextval('"${sequenceName}"') AS value`));
+        // Drizzle/node-postgres returns rows on result.rows; the value comes
+        // back as a string because pg's BIGINT default is string. Parse it —
+        // counter values that overflow Number.MAX_SAFE_INTEGER are not a
+        // realistic concern for the facet-URL use case (we'd run out of
+        // useful URL space long before).
+        const row = result.rows[0];
+        if (row === undefined) {
+            throw new Error(`nextCounterValue: nextval returned no row for group "${groupName}"`);
+        }
+        return typeof row.value === 'number' ? row.value : Number(row.value);
+    }
+}
+export function createCounterCommands(db) {
+    return new CounterCommands(db);
+}

package/dist/modules/storage/storage-commands.d.ts

@@ -19,9 +19,9 @@ export declare class CollectionCommands implements ICollectionCommands {
         version?: number;
         schemaHash?: string;
     }): Promise<{
+        created_at: Date;
+        updated_at: Date;
         id: string;
-        created_at: Date | null;
-        updated_at: Date | null;
         config: unknown;
         path: string;
         singular: string;
@@ -34,6 +34,8 @@ export declare class CollectionCommands implements ICollectionCommands {
         version?: number;
         schemaHash?: string;
     }): Promise<{
+        created_at: Date;
+        updated_at: Date;
         id: string;
         path: string;
         singular: string;
@@ -41,8 +43,6 @@ export declare class CollectionCommands implements ICollectionCommands {
         config: unknown;
         version: number;
         schema_hash: string | null;
-        created_at: Date | null;
-        updated_at: Date | null;
     }[]>;
     delete(id: string): Promise<import("pg").QueryResult<never>>;
 }
@@ -82,9 +82,9 @@ export declare class DocumentCommands implements IDocumentCommands {
         orderKey?: string;
     }): Promise<{
         document: {
+            created_at: Date;
+            updated_at: Date;
             id: string;
-            created_at: Date | null;
-            updated_at: Date | null;
             collection_id: string;
             document_id: string;
             collection_version: number;

package/dist/modules/storage/storage-flatten.js

@@ -152,6 +152,7 @@ const flattenValueFieldData = (field, field_path, value, locale) => {
                 value_float: value,
             };
         case 'integer':
+        case 'counter':
             return {
                 locale,
                 field_path,

package/dist/modules/storage/storage-queries.d.ts

@@ -16,6 +16,8 @@ export declare class CollectionQueries implements ICollectionQueries {
     private db;
     constructor(db: DatabaseConnection);
     getAllCollections(): Promise<{
+        created_at: Date;
+        updated_at: Date;
         id: string;
         path: string;
         singular: string;
@@ -23,13 +25,11 @@ export declare class CollectionQueries implements ICollectionQueries {
         config: unknown;
         version: number;
         schema_hash: string | null;
-        created_at: Date | null;
-        updated_at: Date | null;
     }[]>;
     getCollectionByPath(path: string): Promise<{
+        created_at: Date;
+        updated_at: Date;
         id: string;
-        created_at: Date | null;
-        updated_at: Date | null;
         config: unknown;
         path: string;
         singular: string;
@@ -38,9 +38,9 @@ export declare class CollectionQueries implements ICollectionQueries {
         schema_hash: string | null;
     } | undefined>;
     getCollectionById(id: string): Promise<{
+        created_at: Date;
+        updated_at: Date;
         id: string;
-        created_at: Date | null;
-        updated_at: Date | null;
         config: unknown;
         path: string;
         singular: string;
@@ -192,8 +192,8 @@ export declare class DocumentQueries implements IDocumentQueries {
         document_id: string;
         path: string;
         status: string | null;
-        created_at: Date | null;
-        updated_at: Date | null;
+        created_at: Date;
+        updated_at: Date;
         fields: any;
     } | null>;
     getDocumentByPath({ collection_id, path, locale, reconstruct, readMode, filters, }: {
@@ -208,8 +208,8 @@ export declare class DocumentQueries implements IDocumentQueries {
         document_id: string;
         path: string;
         status: string | null;
-        created_at: Date | null;
-        updated_at: Date | null;
+        created_at: Date;
+        updated_at: Date;
         fields: any;
     } | null>;
     /**

package/dist/modules/storage/storage-queries.js

@@ -1074,11 +1074,22 @@ export class DocumentQueries {
                 return sql `${column} ILIKE ${`%${String(value)}%`}`;
             case '$in': {
                 const arr = value;
-                return sql `${column} = ANY(${arr})`;
+                // Empty `$in` matches nothing — explicit FALSE avoids generating
+                // an invalid empty `IN ()` clause.
+                if (arr.length === 0)
+                    return sql `FALSE`;
+                // Bind each element as its own parameter. Drizzle's `${arr}` would
+                // serialise as a single row-constructor (`($1, $2)`), which Postgres
+                // rejects when compared to a scalar column with `= ANY(...)`.
+                const items = sql.join(arr.map((v) => sql `${v}`), sql `, `);
+                return sql `${column} IN (${items})`;
             }
             case '$nin': {
                 const arr = value;
-                return sql `${column} != ALL(${arr})`;
+                if (arr.length === 0)
+                    return sql `TRUE`;
+                const items = sql.join(arr.map((v) => sql `${v}`), sql `, `);
+                return sql `${column} NOT IN (${items})`;
             }
             default:
                 throw ERR_DATABASE({

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -57,9 +57,9 @@
     "pg": "^8.20.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/admin": "2.1.2",
-    "@byline/auth": "2.1.2",
-    "@byline/core": "2.1.2"
+    "@byline/admin": "2.2.0",
+    "@byline/auth": "2.2.0",
+    "@byline/core": "2.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",

package/dist/lib/test-bootstrap.d.ts

@@ -1,8 +0,0 @@
-/**
- * This Source Code is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
-export {};

package/dist/lib/test-bootstrap.js

@@ -1,27 +0,0 @@
-/**
- * This Source Code is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
-/**
- * Per-test-file bootstrap for node:test integration tests.
- *
- * The `tsx --env-file=.env.test --import ./src/lib/test-bootstrap.ts --test`
- * invocation runs this module once at the start of each test-file process,
- * before any test imports resolve. It:
- *
- *   1. Asserts `POSTGRES_CONNECTION_STRING` targets a `_test` database
- *      (belt; the script-level guard in `common.sh` is the braces).
- *   2. Applies Drizzle migrations (idempotent — cheap on re-run).
- *   3. Truncates all `public` tables so the file starts from a known state.
- *
- * Top-level await ensures the file's own `before()` hooks don't run until
- * the database is ready.
- */
-import { assertTestDatabase, migrateTestDatabase, resetTestDatabase } from './test-db.js';
-const connectionString = process.env.POSTGRES_CONNECTION_STRING;
-assertTestDatabase(connectionString);
-await migrateTestDatabase(connectionString);
-await resetTestDatabase(connectionString);