@byline/db-postgres 1.10.3 → 1.11.1

package/dist/database/schema/index.d.ts

@@ -207,6 +207,25 @@ export declare const documents: import("drizzle-orm/pg-core").PgTableWithColumns
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        order_key: import("drizzle-orm/pg-core").PgColumn<{
+            name: "order_key";
+            tableName: "byline_documents";
+            dataType: "custom";
+            columnType: "PgCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            pgColumnBuilderBrand: "PgCustomColumnBuilderBrand";
+        }>;
         created_at: import("drizzle-orm/pg-core").PgColumn<{
             name: "created_at";
             tableName: "byline_documents";
@@ -818,6 +837,23 @@ export declare const currentDocumentsView: import("drizzle-orm/pg-core").PgViewW
         identity: undefined;
         generated: undefined;
     }, {}, {}>;
+    order_key: import("drizzle-orm/pg-core").PgColumn<{
+        name: "order_key";
+        tableName: "byline_current_documents";
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+    }, {}, {}>;
 }>;
 export declare const currentPublishedDocumentsView: import("drizzle-orm/pg-core").PgViewWithSelection<"byline_current_published_documents", false, {
     id: import("drizzle-orm/pg-core").PgColumn<{
@@ -1007,6 +1043,23 @@ export declare const currentPublishedDocumentsView: import("drizzle-orm/pg-core"
         identity: undefined;
         generated: undefined;
     }, {}, {}>;
+    order_key: import("drizzle-orm/pg-core").PgColumn<{
+        name: "order_key";
+        tableName: "byline_current_published_documents";
+        dataType: "custom";
+        columnType: "PgCustomColumn";
+        data: string;
+        driverParam: string;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+    }, {}, {}>;
 }>;
 export declare const textStore: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "byline_store_text";

package/dist/database/schema/index.js

@@ -6,7 +6,28 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { eq, relations, sql } from 'drizzle-orm';
-import { bigint, boolean, date, decimal, index, integer, jsonb, pgTable, pgView, real, text, time, timestamp, unique, uuid, varchar, } from 'drizzle-orm/pg-core';
+import { bigint, boolean, customType, date, decimal, index, integer, jsonb, pgTable, pgView, real, text, time, timestamp, unique, uuid, varchar, } from 'drizzle-orm/pg-core';
+/**
+ * `varchar(...)` with explicit byte-wise (C) collation.
+ *
+ * Used for `byline_documents.order_key` so the column sorts the same way
+ * JavaScript string comparison does. The fractional-index algorithm in
+ * `@byline/core` (`generateKeyBetween`, `generateNKeysBetween`) is designed
+ * against byte-wise ordering; the database default collation (e.g.
+ * `en_US.utf8` on most modern installs) is locale-aware and disagrees with
+ * JS on cases like `'Zz' vs 'a0'` — which causes a refetch after a drag-
+ * reorder to "snap" the moved row back to its original position.
+ *
+ * Captured here (rather than only in a hand-written migration) so future
+ * regenerations from this schema reproduce the COLLATE clause cleanly.
+ * See migration `0003_order_key_byte_collation.sql` and `docs/ORDERABLE.md`.
+ */
+const varcharByteSorted = customType({
+    dataType(config) {
+        const len = config?.length ?? 255;
+        return `varchar(${len}) COLLATE "C"`;
+    },
+});
 // Collections table
 export const collections = pgTable('byline_collections', {
     id: uuid('id').primaryKey(),
@@ -32,9 +53,22 @@ export const documents = pgTable('byline_documents', {
     collection_id: uuid('collection_id')
         .notNull()
         .references(() => collections.id, { onDelete: 'cascade' }),
+    // Fractional-index sort key for collections with `orderable: true` in
+    // their admin config. Null on collections that haven't opted in, and on
+    // pre-existing rows in newly-`orderable` collections (sort NULLS LAST).
+    // Admin metadata — never per-version, never EAV; updated by the reorder
+    // server fn without bumping documentVersions.
+    //
+    // Uses `varcharByteSorted` (COLLATE "C") so DB ordering matches JS string
+    // comparison — the fractional-index algorithm requires this. See
+    // `varcharByteSorted` above and docs/ORDERABLE.md.
+    order_key: varcharByteSorted('order_key', { length: 128 }),
     created_at: timestamp('created_at').defaultNow(),
     updated_at: timestamp('updated_at').defaultNow(),
-}, (table) => [index('idx_documents_collection').on(table.collection_id)]);
+}, (table) => [
+    index('idx_documents_collection').on(table.collection_id),
+    index('idx_documents_collection_order').on(table.collection_id, table.order_key),
+]);
 // Document versions table
 export const documentVersions = pgTable('byline_document_versions', {
     id: uuid('id').primaryKey(), // UUIDv7 versioning by default
@@ -143,6 +177,11 @@ export const currentDocumentsView = pgView('byline_current_documents').as((qb) =
     })
         .from(documentVersions)
         .where(eq(documentVersions.is_deleted, false)));
+    // `order_key` is sourced from `byline_documents` (the logical-document
+    // row, not the version row). Joining it through the view keeps
+    // `d.order_key` addressable in findDocuments' ORDER BY without an
+    // ad-hoc join per query. Always nullable; null sorts last for
+    // collections that haven't opted in to `orderable: true`.
     return qb
         .with(sq)
         .select({
@@ -157,8 +196,10 @@ export const currentDocumentsView = pgView('byline_current_documents').as((qb) =
         updated_at: sq.updated_at,
         created_by: sq.created_by,
         change_summary: sq.change_summary,
+        order_key: documents.order_key,
     })
         .from(sq)
+        .innerJoin(documents, eq(documents.id, sq.document_id))
         .where(eq(sq.rn, 1));
 });
 // Current Published Documents View - gets the latest version of each logical
@@ -198,8 +239,10 @@ export const currentPublishedDocumentsView = pgView('byline_current_published_do
         updated_at: sq.updated_at,
         created_by: sq.created_by,
         change_summary: sq.change_summary,
+        order_key: documents.order_key,
     })
         .from(sq)
+        .innerJoin(documents, eq(documents.id, sq.document_id))
         .where(eq(sq.rn, 1));
 });
 // Base field values structure

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

@@ -22,10 +22,10 @@ export declare class CollectionCommands implements ICollectionCommands {
         id: string;
         created_at: Date | null;
         updated_at: Date | null;
+        config: unknown;
         path: string;
         singular: string;
         plural: string;
-        config: unknown;
         version: number;
         schema_hash: string | null;
     }[]>;
@@ -79,6 +79,7 @@ export declare class DocumentCommands implements IDocumentCommands {
         status?: string;
         createdBy?: string;
         previousVersionId?: string;
+        orderKey?: string;
     }): Promise<{
         document: {
             id: string;
@@ -133,6 +134,15 @@ export declare class DocumentCommands implements IDocumentCommands {
     softDeleteDocument(params: {
         document_id: string;
     }): Promise<number>;
+    /**
+     * Write `order_key` on a single `byline_documents` row. Single-column
+     * metadata update — no new version row, no `documentVersions` touch.
+     * `updated_at` on the document row is bumped so list caches invalidate.
+     */
+    setOrderKey(params: {
+        document_id: string;
+        order_key: string;
+    }): Promise<void>;
 }
 export declare function createCommandBuilders(db: DatabaseConnection, defaultContentLocale: string): {
     collections: CollectionCommands;

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

@@ -76,6 +76,7 @@ export class DocumentCommands {
                     .values({
                     id: documentId,
                     collection_id: params.collectionId,
+                    order_key: params.orderKey ?? null,
                 })
                     .returning()
                     .then(getFirstOrThrow('Failed to create document'));
@@ -287,6 +288,20 @@ export class DocumentCommands {
             .where(eq(documentVersions.document_id, params.document_id));
         return result.rowCount ?? 0;
     }
+    /**
+     * Write `order_key` on a single `byline_documents` row. Single-column
+     * metadata update — no new version row, no `documentVersions` touch.
+     * `updated_at` on the document row is bumped so list caches invalidate.
+     */
+    async setOrderKey(params) {
+        await this.db
+            .update(documents)
+            .set({
+            order_key: params.order_key,
+            updated_at: new Date(),
+        })
+            .where(eq(documents.id, params.document_id));
+    }
 }
 export function createCommandBuilders(db, defaultContentLocale) {
     return {

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

@@ -30,10 +30,10 @@ export declare class CollectionQueries implements ICollectionQueries {
         id: string;
         created_at: Date | null;
         updated_at: Date | null;
+        config: unknown;
         path: string;
         singular: string;
         plural: string;
-        config: unknown;
         version: number;
         schema_hash: string | null;
     } | undefined>;
@@ -41,10 +41,10 @@ export declare class CollectionQueries implements ICollectionQueries {
         id: string;
         created_at: Date | null;
         updated_at: Date | null;
+        config: unknown;
         path: string;
         singular: string;
         plural: string;
-        config: unknown;
         version: number;
         schema_hash: string | null;
     } | undefined>;
@@ -306,6 +306,48 @@ export declare class DocumentQueries implements IDocumentQueries {
         document_ids: string[];
         status?: string;
     }): Promise<Set<string>>;
+    /**
+     * getLastOrderKey
+     *
+     * Largest `order_key` currently in use for the given collection. Used
+     * at create-time on `orderable: true` collections to append the new
+     * row at the end. Returns `null` when no keyed rows exist yet.
+     */
+    getLastOrderKey({ collection_id }: {
+        collection_id: string;
+    }): Promise<string | null>;
+    /**
+     * getNeighborOrderKeys
+     *
+     * Resolve the `order_key` values bracketing a target gap in one query.
+     * `before_document_id` is the doc the moved row should land *after*;
+     * `after_document_id` is the doc it should land *before*. Either or
+     * both may be null (append / prepend / empty collection).
+     *
+     * Resolves both keys in a single round trip to keep the read consistent
+     * with the next-key computation that follows in the caller.
+     */
+    getNeighborOrderKeys({ collection_id, before_document_id, after_document_id, }: {
+        collection_id: string;
+        before_document_id: string | null;
+        after_document_id: string | null;
+    }): Promise<{
+        left: string | null;
+        right: string | null;
+    }>;
+    /**
+     * getCanonicalDocumentOrder
+     *
+     * Returns every document in the collection in its canonical list-view
+     * order: `order_key ASC NULLS LAST, created_at DESC`. Used by the reorder
+     * server fn for backfill and recovery from key corruption.
+     */
+    getCanonicalDocumentOrder({ collection_id, }: {
+        collection_id: string;
+    }): Promise<Array<{
+        id: string;
+        order_key: string | null;
+    }>>;
     /**
      * getDocumentCountsByStatus
      *

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

@@ -10,8 +10,8 @@
 // logger. A future refactor could inject the logger at construction time by
 // either deferring adapter construction or accepting a lazy logger parameter.
 import { ERR_DATABASE, ERR_NOT_FOUND, getLogger } from '@byline/core';
-import { and, eq, inArray, sql } from 'drizzle-orm';
-import { collections, currentDocumentsView, currentPublishedDocumentsView, documentPaths, documentVersions, metaStore, } from '../../database/schema/index.js';
+import { and, desc, eq, inArray, isNotNull, sql } from 'drizzle-orm';
+import { collections, currentDocumentsView, currentPublishedDocumentsView, documentPaths, documents, documentVersions, metaStore, } from '../../database/schema/index.js';
 import { extractFlattenedFieldValue, restoreFieldSetData } from './storage-restore.js';
 import { allStoreTypes, storeSelectList, storeTableNames, } from './storage-store-manifest.js';
 import { resolveStoreTypes } from './storage-utils.js';
@@ -601,6 +601,67 @@ export class DocumentQueries {
             .groupBy(documentVersions.document_id);
         return new Set(rows.map((r) => r.document_id));
     }
+    /**
+     * getLastOrderKey
+     *
+     * Largest `order_key` currently in use for the given collection. Used
+     * at create-time on `orderable: true` collections to append the new
+     * row at the end. Returns `null` when no keyed rows exist yet.
+     */
+    async getLastOrderKey({ collection_id }) {
+        const rows = await this.db
+            .select({ order_key: documents.order_key })
+            .from(documents)
+            .where(and(eq(documents.collection_id, collection_id), isNotNull(documents.order_key)))
+            .orderBy(desc(documents.order_key))
+            .limit(1);
+        return rows[0]?.order_key ?? null;
+    }
+    /**
+     * getNeighborOrderKeys
+     *
+     * Resolve the `order_key` values bracketing a target gap in one query.
+     * `before_document_id` is the doc the moved row should land *after*;
+     * `after_document_id` is the doc it should land *before*. Either or
+     * both may be null (append / prepend / empty collection).
+     *
+     * Resolves both keys in a single round trip to keep the read consistent
+     * with the next-key computation that follows in the caller.
+     */
+    async getNeighborOrderKeys({ collection_id, before_document_id, after_document_id, }) {
+        const ids = [];
+        if (before_document_id)
+            ids.push(before_document_id);
+        if (after_document_id)
+            ids.push(after_document_id);
+        if (ids.length === 0) {
+            return { left: null, right: null };
+        }
+        const rows = await this.db
+            .select({ id: documents.id, order_key: documents.order_key })
+            .from(documents)
+            .where(and(eq(documents.collection_id, collection_id), inArray(documents.id, ids)));
+        const byId = new Map(rows.map((r) => [r.id, r.order_key]));
+        return {
+            left: before_document_id ? (byId.get(before_document_id) ?? null) : null,
+            right: after_document_id ? (byId.get(after_document_id) ?? null) : null,
+        };
+    }
+    /**
+     * getCanonicalDocumentOrder
+     *
+     * Returns every document in the collection in its canonical list-view
+     * order: `order_key ASC NULLS LAST, created_at DESC`. Used by the reorder
+     * server fn for backfill and recovery from key corruption.
+     */
+    async getCanonicalDocumentOrder({ collection_id, }) {
+        const rows = await this.db
+            .select({ id: documents.id, order_key: documents.order_key })
+            .from(documents)
+            .where(eq(documents.collection_id, collection_id))
+            .orderBy(sql `${documents.order_key} ASC NULLS LAST`, desc(documents.created_at));
+        return rows;
+    }
     /**
      * getDocumentCountsByStatus
      *
@@ -1037,6 +1098,16 @@ export class DocumentQueries {
      * arrives.
      */
     buildDocumentOrderClause(orderBy, direction) {
+        // `order_key` is the fractional-index column for `orderable: true`
+        // collections. Always sort NULLS LAST with a `created_at DESC` tiebreaker
+        // so unkeyed rows (existing rows in a newly-opted-in collection, or rows
+        // from before the column existed) fall to the bottom in a stable order
+        // until the editor drags them into position.
+        if (orderBy === 'order_key') {
+            return direction === 'desc'
+                ? sql `d.order_key DESC NULLS LAST, d.created_at DESC`
+                : sql `d.order_key ASC NULLS LAST, d.created_at DESC`;
+        }
         const columnMap = {
             created_at: 'd.created_at',
             updated_at: 'd.updated_at',

package/package.json

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