feat(tables): add order_key column, fractional-indexing util, and ordering flag (off)

Author: TheodoreSpeaks

apps/sim/lib/core/config/env.ts

@@ -68,6 +68,7 @@ export const env = createEnv({
     ENTERPRISE_TIER_COST_LIMIT:            z.number().optional(),                  // Cost limit for enterprise tier users
     ENTERPRISE_STORAGE_LIMIT_GB:           z.number().optional().default(500),     // Default storage limit in GB for enterprise tier (can be overridden per org)
     BILLING_ENABLED:                       z.boolean().optional(),                 // Enable billing enforcement and usage tracking
+    TABLES_FRACTIONAL_ORDERING:            z.boolean().optional(),                 // Order table rows by fractional order_key (O(1) insert/delete) instead of integer position
 
     // Table feature limits (per plan). Apply when billing is disabled (free tier defaults) or for billed plans.
     FREE_TABLES_LIMIT:                     z.number().optional(),                  // Max user tables per workspace on free tier (default: 3)

apps/sim/lib/core/config/feature-flags.ts

@@ -36,6 +36,14 @@ export const isHosted = appHostname === 'sim.ai' || appHostname.endsWith('.sim.a
  */
 export const isBillingEnabled = isTruthy(env.BILLING_ENABLED)
 
+/**
+ * Order table rows by fractional `order_key` (O(1) insert/delete) instead of the
+ * legacy integer `position`. When off, behavior is unchanged. Keys are written
+ * regardless of this flag; it only controls which column is authoritative for
+ * reads/ordering and whether inserts/deletes reshift positions.
+ */
+export const isTablesFractionalOrderingEnabled = isTruthy(env.TABLES_FRACTIONAL_ORDERING)
+
 /**
  * Is email verification enabled
  */

apps/sim/lib/table/order-key.ts

@@ -0,0 +1,33 @@
+/**
+ * Fractional order keys for table-row ordering.
+ *
+ * A row's order is a base-62 string key, not an integer position. Inserting
+ * between two rows mints a key strictly between their keys, so no other row's
+ * key changes — insert and delete become O(1) (no position reshift / recompact).
+ *
+ * Thin wrapper over `fractional-indexing` (Figma/rocicorp algorithm) so the
+ * implementation is swappable. Keys never run out (variable-length strings);
+ * the only cost is gradual length growth under repeated same-spot inserts.
+ */
+
+import { generateKeyBetween, generateNKeysBetween } from 'fractional-indexing'
+
+/**
+ * Returns a key that sorts strictly between `a` and `b`. Pass `null` for an open
+ * end: `keyBetween(null, first)` prepends, `keyBetween(last, null)` appends,
+ * `keyBetween(null, null)` is the first key in an empty table.
+ *
+ * @throws if `a >= b` (callers must pass ordered, distinct bounds)
+ */
+export function keyBetween(a: string | null, b: string | null): string {
+  return generateKeyBetween(a, b)
+}
+
+/**
+ * Returns `n` keys evenly spaced strictly between `a` and `b` (same open-end
+ * semantics as {@link keyBetween}). Used for batch inserts and the backfill
+ * (`nKeysBetween(null, null, count)` mints an ordered run for an empty range).
+ */
+export function nKeysBetween(a: string | null, b: string | null, n: number): string[] {
+  return generateNKeysBetween(a, b, n)
+}

apps/sim/package.json

@@ -132,6 +132,7 @@
     "es-toolkit": "1.45.1",
     "ffmpeg-static": "5.3.0",
     "fluent-ffmpeg": "2.1.3",
+    "fractional-indexing": "3.2.0",
     "framer-motion": "^12.5.0",
     "free-email-domains": "1.2.25",
     "google-auth-library": "10.5.0",

bun.lock

@@ -0,0 +1,2 @@
+ALTER TABLE "user_table_rows" ADD COLUMN "order_key" text;--> statement-breakpoint
+CREATE INDEX "user_table_rows_table_order_key_idx" ON "user_table_rows" USING btree ("table_id","order_key","id");