@pylonsync/sync 0.3.50 → 0.3.51

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.50",
+  "version": "0.3.51",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -255,6 +255,46 @@ export class LocalStore {
     return tempId;
   }
 
+  /**
+   * Apply an optimistic insert with a caller-provided id.
+   *
+   * Used by `useMutation({ optimistic })`: the React hook generates a
+   * Pylon-shaped id (40-char hex via `generateId()`), threads it
+   * through the mutation args as `_optimisticId`, and the server
+   * function honors it on `ctx.db.insert("Entity", { id, ... })`.
+   * Because the optimistic ghost and the canonical row share the same
+   * `row_id`, the WS broadcast that follows the mutation lands as a
+   * field-level merge on top of the optimistic — no delete-then-replace
+   * flash, no temp-row swap.
+   *
+   * Different from `optimisticInsert` (above) which mints a `_pending_`
+   * id the server can't possibly know about. Use that for fire-and-
+   * forget UI affordances, and this one whenever the canonical insert
+   * needs to map back to the same row.
+   */
+  optimisticInsertWithId(entity: string, id: string, data: Row): void {
+    if (!this.tables.has(entity)) {
+      this.tables.set(entity, new Map());
+    }
+    this.tables.get(entity)!.set(id, { ...data, id });
+    this.notify();
+  }
+
+  /**
+   * Roll back an optimistic insert without leaving a tombstone.
+   *
+   * Counterpart to `optimisticInsertWithId`. When a mutation rejects,
+   * we want the ghost row gone but we do NOT want a tombstone — a
+   * future legitimate insert with the same id (e.g. user retries the
+   * mutation, or a workflow eventually creates the row) must not be
+   * blocked. `optimisticDelete` records a MAX_SAFE_INTEGER tombstone
+   * which is the wrong semantic here; this is just a plain remove.
+   */
+  rollbackOptimisticInsert(entity: string, id: string): void {
+    const removed = this.tables.get(entity)?.delete(id);
+    if (removed) this.notify();
+  }
+
   /** Apply an optimistic update. */
   optimisticUpdate(entity: string, id: string, data: Partial<Row>): void {
     const table = this.tables.get(entity);
@@ -460,6 +500,37 @@ export interface SyncEngineConfig {
  * Generate a stable client_id. Prefers a persisted id from `storage`
  * (so a reload keeps the same identifier) and falls back to a fresh UUID.
  */
+/**
+ * Generate a Pylon-shaped row id (40-char lowercase hex).
+ *
+ * Mirrors the runtime's `generate_id` shape: 32 hex of milliseconds
+ * since epoch (extended to nanos so it lex-sorts alongside server-
+ * generated ids) + 8 hex of a per-tab counter. Lex-sortable, monotonic
+ * within a tab, statistically unique across tabs (the timestamp
+ * disambiguates almost every cross-tab collision; the counter handles
+ * the rest within a single tick).
+ *
+ * Used by `useMutation({ optimistic })` to mint client-side ids that
+ * the runtime will accept verbatim — so the optimistic ghost and the
+ * canonical row share the same `row_id` and the WS broadcast is an
+ * idempotent merge instead of a delete-then-replace flash.
+ *
+ * Apps can call this directly when they need a stable id earlier than
+ * the mutation (e.g. to reference the row from another optimistic
+ * insert in the same gesture).
+ */
+let idCounter = 0;
+export function generateId(): string {
+  // BigInt to dodge the 2^53 ceiling — `Date.now() * 1_000_000` busts
+  // Number.MAX_SAFE_INTEGER for any timestamp past 1973. Hex output is
+  // padded to 32 chars so it lex-sorts at width boundaries (a 39-char
+  // id sorts before a 40-char one even when the suffix is larger,
+  // which would corrupt cursor pagination).
+  const nanos = BigInt(Date.now()) * 1_000_000n;
+  const seq = idCounter++ >>> 0;
+  return nanos.toString(16).padStart(32, "0") + seq.toString(16).padStart(8, "0");
+}
+
 function generateClientId(storage: import("./storage").Storage): string {
   const key = "pylon:client_id";
   const existing = storage.get(key);
@@ -688,6 +759,7 @@ export class SyncEngine {
     if (this.running) return;
     this.running = true;
     this.setConnectionStatus("connecting");
+    warnIfMisconfigured(this.config.baseUrl);
 
     // Load persisted data if available.
     const shouldPersist = this.config.persist !== false && typeof indexedDB !== "undefined";
@@ -1592,6 +1664,43 @@ export async function getServerData(
 // Convenience factory
 // ---------------------------------------------------------------------------
 
+/**
+ * One-shot guard: detect the most common production misconfig — a
+ * deployed app running on HTTPS with `baseUrl` still pointing at a
+ * `localhost` API. Symptom in the wild: blank screen, "Failed to
+ * fetch" in DevTools, browser blocking mixed-content WS upgrades.
+ *
+ * The check fires once per page load and is browser-only (server-
+ * side renders see localhost as a legitimate target). It's a loud
+ * `console.error` block — surfaces in DevTools, Vercel deploy logs,
+ * and Sentry-style trackers — but doesn't throw, so existing apps
+ * can't lock up on a misconfigured deploy.
+ */
+let warnedMisconfig = false;
+function warnIfMisconfigured(baseUrl: string): void {
+  if (warnedMisconfig) return;
+  if (typeof window === "undefined") return;
+  const pageHttps = window.location?.protocol === "https:";
+  const apiLocalhost =
+    /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|\/|$)/.test(baseUrl);
+  if (!pageHttps || !apiLocalhost) return;
+  warnedMisconfig = true;
+  // eslint-disable-next-line no-console
+  console.error(
+    "[pylon] Misconfigured deployment:\n" +
+      "  Page is on " + window.location.origin + " (https)\n" +
+      "  Pylon baseUrl is " + baseUrl + " (localhost)\n" +
+      "\n" +
+      "Likely cause: NEXT_PUBLIC_PYLON_URL (or your framework's equivalent)\n" +
+      "is unset in this deployment. The client falls back to localhost,\n" +
+      "and every API request fails with 'Failed to fetch'.\n" +
+      "\n" +
+      "Fix: set NEXT_PUBLIC_PYLON_URL=https://<your-pylon-host> in the\n" +
+      "deployment env, then redeploy. If your dashboard proxies /api/*\n" +
+      "to the backend same-origin, set it to '' (empty string) instead.",
+  );
+}
+
 /**
  * Create a sync engine connected to the pylon backend.
  *