@contrail/documents 1.14.0 → 1.15.0-alpha.4626e64

package/CHANGELOG.md

@@ -5,6 +5,12 @@ 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).
 
+## [1.15.0] - 2026-08-18
+
+### Added
+
+- `isValidSortIndex` — whether a value is a usable fractional-indexing key. `fractional-indexing` keeps its own `validateOrderKey` private, so callers that need to check a key before storing it had no way to do so beyond a non-empty-string test. A key that passes that test but breaks the grammar still sorts, so ordering looks fine; the failure surfaces later, when the next insert beside it calls `generateKeyBetween` and throws. One point is stricter than the library: every character must be in the base-62 digit set, since a key holding anything else can sort below the integer part it claims.
+
 ## [1.14.0] - 2026-07-29
 
 ### Added

package/lib/sort-index.d.ts

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

package/lib/sort-index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.allElementsHaveSortIndex = allElementsHaveSortIndex;
+exports.isValidSortIndex = isValidSortIndex;
 exports.buildKeyBetween = buildKeyBetween;
 exports.buildNKeysBetween = buildNKeysBetween;
 exports.compareSortIndex = compareSortIndex;
@@ -9,6 +10,26 @@ function allElementsHaveSortIndex(elements) {
     return elements.every((element) => typeof element.sortIndex === 'string' &&
         element.sortIndex.length > 0);
 }
+const SMALLEST_INTEGER = 'A00000000000000000000000000';
+function getIntegerPartLength(head) {
+    if (head >= 'a' && head <= 'z')
+        return head.charCodeAt(0) - 'a'.charCodeAt(0) + 2;
+    if (head >= 'A' && head <= 'Z')
+        return 'Z'.charCodeAt(0) - head.charCodeAt(0) + 2;
+    return null;
+}
+function isValidSortIndex(sortIndex) {
+    if (typeof sortIndex !== 'string' || sortIndex.length === 0)
+        return false;
+    if (sortIndex === SMALLEST_INTEGER)
+        return false;
+    if (![...sortIndex].every((character) => fractional_indexing_1.BASE_62_DIGITS.includes(character)))
+        return false;
+    const integerPartLength = getIntegerPartLength(sortIndex[0]);
+    if (integerPartLength === null || integerPartLength > sortIndex.length)
+        return false;
+    return !sortIndex.slice(integerPartLength).endsWith('0');
+}
 function buildKeyBetween(a, b) {
     return (0, fractional_indexing_1.generateKeyBetween)(a, b);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "1.14.0",
+  "version": "1.15.0-alpha.4626e64",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",