@contrail/documents 2.2.1 → 2.3.0-alpha.8377be9

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to `@contrail/documents` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-09-21
+
+### Added
+
+- `isValidSortIndex(sortIndex)` — whether a value is a key `fractional-indexing` could have produced, so every client writing a sort index is held to one definition of valid rather than each caller inventing its own. `fractional-indexing` keeps its `validateOrderKey` private, so the check asks the generator to mint a key after the candidate: that path validates its bound first and cannot fail for any other reason. The generator's own grammar check ignores the digit alphabet, and accepts `a0!` or `a0 `, so the candidate is screened against the exported `BASE_62_DIGITS` first. Costs ~130ns for a short key and ~350ns for a 387-character one.
+
+### Changed
+
+- `allElementsHaveSortIndex` now requires each element's key to be valid, not merely a non-empty string. Callers that treat an unkeyed collection as needing fresh keys — board snapshot restore is the one today — now also re-key a collection whose keys are present but malformed, instead of restoring ordering that cannot sort.
+- `SortOrderErrorMessage.SORT_INDEX_NOT_USABLE` describes the real rule ("sortIndex must be a valid fractional index") rather than "must be a non-empty string". The `SORT_INDEX_NOT_USABLE` code is unchanged.
+
 ## [2.2.1] - 2026-09-15
 
 ### Changed

package/lib/sort-index.d.ts

@@ -1,4 +1,5 @@
 import { DocumentElement } from './types';
+export declare function isValidSortIndex(sortIndex: unknown): sortIndex is string;
 export declare function allElementsHaveSortIndex(elements: unknown[]): boolean;
 export declare function buildKeyBetween(a: string | null, b: string | null): string;
 export declare function buildNKeysBetween(a: string | null, b: string | null, n: number): string[];

package/lib/sort-index.js

@@ -1,13 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidSortIndex = isValidSortIndex;
 exports.allElementsHaveSortIndex = allElementsHaveSortIndex;
 exports.buildKeyBetween = buildKeyBetween;
 exports.buildNKeysBetween = buildNKeysBetween;
 exports.compareSortIndex = compareSortIndex;
 const fractional_indexing_1 = require("fractional-indexing");
+const SORT_INDEX_DIGITS = new RegExp(`^[${fractional_indexing_1.BASE_62_DIGITS.replace(/[\\\]^-]/g, (digit) => `\\${digit}`)}]+$`);
+function isValidSortIndex(sortIndex) {
+    if (typeof sortIndex !== 'string' || !SORT_INDEX_DIGITS.test(sortIndex)) {
+        return false;
+    }
+    try {
+        (0, fractional_indexing_1.generateKeyBetween)(sortIndex, null);
+    }
+    catch (_a) {
+        return false;
+    }
+    return true;
+}
 function allElementsHaveSortIndex(elements) {
-    return elements.every((element) => typeof element.sortIndex === 'string' &&
-        element.sortIndex.length > 0);
+    return elements.every((element) => isValidSortIndex(element.sortIndex));
 }
 function buildKeyBetween(a, b) {
     return (0, fractional_indexing_1.generateKeyBetween)(a, b);

package/lib/sort-order-errors.d.ts

@@ -6,5 +6,5 @@ export declare enum SortOrderErrorCode {
 export declare enum SortOrderErrorMessage {
     SORT_MIGRATION_IN_PROGRESS = "Sort order is being migrated for this document; editing is briefly locked",
     SORT_MODE_MISMATCH = "Ordering write does not match the document's sort mode",
-    SORT_INDEX_NOT_USABLE = "sortIndex must be a non-empty string"
+    SORT_INDEX_NOT_USABLE = "sortIndex must be a valid fractional index"
 }

package/lib/sort-order-errors.js

@@ -11,5 +11,5 @@ var SortOrderErrorMessage;
 (function (SortOrderErrorMessage) {
     SortOrderErrorMessage["SORT_MIGRATION_IN_PROGRESS"] = "Sort order is being migrated for this document; editing is briefly locked";
     SortOrderErrorMessage["SORT_MODE_MISMATCH"] = "Ordering write does not match the document's sort mode";
-    SortOrderErrorMessage["SORT_INDEX_NOT_USABLE"] = "sortIndex must be a non-empty string";
+    SortOrderErrorMessage["SORT_INDEX_NOT_USABLE"] = "sortIndex must be a valid fractional index";
 })(SortOrderErrorMessage || (exports.SortOrderErrorMessage = SortOrderErrorMessage = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "2.2.1",
+  "version": "2.3.0-alpha.8377be9",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",