@moloodev/editor-sdk 0.0.0-stage → 0.1.0

package/src/commands/when/parse.ts

@@ -0,0 +1,276 @@
+import { WhenParseError, type WhenExpr } from "./types";
+
+type Token =
+  | { kind: "ident"; value: string; offset: number }
+  | { kind: "number"; value: number; offset: number }
+  | { kind: "string"; value: string; offset: number }
+  | { kind: "true"; offset: number }
+  | { kind: "false"; offset: number }
+  | { kind: "&&"; offset: number }
+  | { kind: "||"; offset: number }
+  | { kind: "=="; offset: number }
+  | { kind: "!="; offset: number }
+  | { kind: "<="; offset: number }
+  | { kind: ">="; offset: number }
+  | { kind: "<"; offset: number }
+  | { kind: ">"; offset: number }
+  | { kind: "!"; offset: number }
+  | { kind: "("; offset: number }
+  | { kind: ")"; offset: number };
+
+function isIdentStart(ch: string): boolean {
+  return /[A-Za-z_]/.test(ch);
+}
+
+function isIdentPart(ch: string): boolean {
+  return /[A-Za-z0-9_]/.test(ch);
+}
+
+function tokenize(source: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+
+  while (i < source.length) {
+    const ch = source[i]!;
+    if (/\s/.test(ch)) {
+      i += 1;
+      continue;
+    }
+
+    if (source.startsWith("&&", i)) {
+      tokens.push({ kind: "&&", offset: i });
+      i += 2;
+      continue;
+    }
+    if (source.startsWith("||", i)) {
+      tokens.push({ kind: "||", offset: i });
+      i += 2;
+      continue;
+    }
+    if (source.startsWith("==", i)) {
+      tokens.push({ kind: "==", offset: i });
+      i += 2;
+      continue;
+    }
+    if (source.startsWith("!=", i)) {
+      tokens.push({ kind: "!=", offset: i });
+      i += 2;
+      continue;
+    }
+    if (source.startsWith("<=", i)) {
+      tokens.push({ kind: "<=", offset: i });
+      i += 2;
+      continue;
+    }
+    if (source.startsWith(">=", i)) {
+      tokens.push({ kind: ">=", offset: i });
+      i += 2;
+      continue;
+    }
+    if (ch === "<") {
+      tokens.push({ kind: "<", offset: i });
+      i += 1;
+      continue;
+    }
+    if (ch === ">") {
+      tokens.push({ kind: ">", offset: i });
+      i += 1;
+      continue;
+    }
+    if (ch === "!") {
+      tokens.push({ kind: "!", offset: i });
+      i += 1;
+      continue;
+    }
+    if (ch === "(") {
+      tokens.push({ kind: "(", offset: i });
+      i += 1;
+      continue;
+    }
+    if (ch === ")") {
+      tokens.push({ kind: ")", offset: i });
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'" || ch === '"') {
+      const quote = ch;
+      const start = i;
+      i += 1;
+      let value = "";
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === "\\") {
+          i += 1;
+          if (i >= source.length) {
+            throw new WhenParseError("Unterminated string escape", start);
+          }
+          value += source[i]!;
+          i += 1;
+          continue;
+        }
+        value += source[i]!;
+        i += 1;
+      }
+      if (i >= source.length) {
+        throw new WhenParseError("Unterminated string", start);
+      }
+      i += 1;
+      tokens.push({ kind: "string", value, offset: start });
+      continue;
+    }
+
+    if (/[0-9]/.test(ch) || (ch === "-" && /[0-9]/.test(source[i + 1] ?? ""))) {
+      const start = i;
+      let raw = "";
+      if (ch === "-") {
+        raw += ch;
+        i += 1;
+      }
+      while (i < source.length && /[0-9.]/.test(source[i]!)) {
+        raw += source[i]!;
+        i += 1;
+      }
+      const value = Number(raw);
+      if (!Number.isFinite(value)) {
+        throw new WhenParseError(`Invalid number "${raw}"`, start);
+      }
+      tokens.push({ kind: "number", value, offset: start });
+      continue;
+    }
+
+    if (isIdentStart(ch)) {
+      const start = i;
+      let value = "";
+      while (i < source.length && isIdentPart(source[i]!)) {
+        value += source[i]!;
+        i += 1;
+      }
+      if (value === "true") {
+        tokens.push({ kind: "true", offset: start });
+      } else if (value === "false") {
+        tokens.push({ kind: "false", offset: start });
+      } else {
+        tokens.push({ kind: "ident", value, offset: start });
+      }
+      continue;
+    }
+
+    throw new WhenParseError(`Unexpected character "${ch}"`, i);
+  }
+
+  return tokens;
+}
+
+class Parser {
+  private index = 0;
+
+  constructor(private readonly tokens: Token[]) {}
+
+  parse(): WhenExpr {
+    const expr = this.parseOr();
+    if (this.index < this.tokens.length) {
+      const token = this.tokens[this.index]!;
+      throw new WhenParseError("Unexpected token after expression", token.offset);
+    }
+    return expr;
+  }
+
+  private peek(): Token | undefined {
+    return this.tokens[this.index];
+  }
+
+  private advance(): Token {
+    const token = this.tokens[this.index];
+    if (!token) {
+      throw new WhenParseError("Unexpected end of expression", 0);
+    }
+    this.index += 1;
+    return token;
+  }
+
+  private parseOr(): WhenExpr {
+    let left = this.parseAnd();
+    while (this.peek()?.kind === "||") {
+      this.advance();
+      const right = this.parseAnd();
+      left = { kind: "binary", op: "||", left, right };
+    }
+    return left;
+  }
+
+  private parseAnd(): WhenExpr {
+    let left = this.parseCompare();
+    while (this.peek()?.kind === "&&") {
+      this.advance();
+      const right = this.parseCompare();
+      left = { kind: "binary", op: "&&", left, right };
+    }
+    return left;
+  }
+
+  private parseCompare(): WhenExpr {
+    const left = this.parseUnary();
+    const peek = this.peek();
+    if (
+      peek &&
+      (peek.kind === "==" ||
+        peek.kind === "!=" ||
+        peek.kind === "<" ||
+        peek.kind === "<=" ||
+        peek.kind === ">" ||
+        peek.kind === ">=")
+    ) {
+      const op = this.advance().kind as "==" | "!=" | "<" | "<=" | ">" | ">=";
+      const right = this.parseUnary();
+      return { kind: "binary", op, left, right };
+    }
+    return left;
+  }
+
+  private parseUnary(): WhenExpr {
+    if (this.peek()?.kind === "!") {
+      this.advance();
+      return { kind: "unary", op: "!", arg: this.parseUnary() };
+    }
+    return this.parsePrimary();
+  }
+
+  private parsePrimary(): WhenExpr {
+    const token = this.advance();
+    switch (token.kind) {
+      case "true":
+        return { kind: "literal", value: true };
+      case "false":
+        return { kind: "literal", value: false };
+      case "number":
+        return { kind: "literal", value: token.value };
+      case "string":
+        return { kind: "literal", value: token.value };
+      case "ident":
+        return { kind: "key", name: token.value };
+      case "(": {
+        const expr = this.parseOr();
+        const close = this.advance();
+        if (close.kind !== ")") {
+          throw new WhenParseError("Expected closing parenthesis", close.offset);
+        }
+        return expr;
+      }
+      default:
+        throw new WhenParseError("Expected expression", token.offset);
+    }
+  }
+}
+
+/** Parse a when-clause into an AST. Throws WhenParseError on failure. */
+export function parseWhen(source: string): WhenExpr {
+  const trimmed = source.trim();
+  if (!trimmed) {
+    throw new WhenParseError("Empty when clause", 0);
+  }
+  const tokens = tokenize(trimmed);
+  if (tokens.length === 0) {
+    throw new WhenParseError("Empty when clause", 0);
+  }
+  return new Parser(tokens).parse();
+}

package/src/commands/when/types.ts

@@ -0,0 +1,24 @@
+export type ContextValue = string | number | boolean | undefined;
+
+export type ContextKeys = Readonly<Record<string, ContextValue>>;
+
+export type WhenExpr =
+  | { kind: "literal"; value: boolean | number | string }
+  | { kind: "key"; name: string }
+  | { kind: "unary"; op: "!"; arg: WhenExpr }
+  | {
+      kind: "binary";
+      op: "&&" | "||" | "==" | "!=" | "<" | "<=" | ">" | ">=";
+      left: WhenExpr;
+      right: WhenExpr;
+    };
+
+export class WhenParseError extends Error {
+  readonly offset: number;
+
+  constructor(message: string, offset: number) {
+    super(message);
+    this.name = "WhenParseError";
+    this.offset = offset;
+  }
+}

package/src/commands/when/validate.ts

@@ -0,0 +1,20 @@
+import { parseWhen } from "./parse";
+import { WhenParseError } from "./types";
+
+export type WhenValidationIssue = {
+  message: string;
+  offset: number;
+};
+
+/** Returns parse issues for a when clause, or an empty array if valid. */
+export function validateWhenClause(source: string): WhenValidationIssue[] {
+  try {
+    parseWhen(source);
+    return [];
+  } catch (err) {
+    if (err instanceof WhenParseError) {
+      return [{ message: err.message, offset: err.offset }];
+    }
+    return [{ message: String(err), offset: 0 }];
+  }
+}

package/src/crdt/awareness.ts

@@ -0,0 +1,29 @@
+import { Awareness } from "./yjs";
+import type { Doc } from "./doc";
+
+export type Presence = Awareness;
+
+export function createAwareness(doc: Doc): Presence {
+  return new Awareness(doc);
+}
+
+export function setLocalPresence(
+  presence: Presence,
+  state: Record<string, unknown>,
+): void {
+  presence.setLocalState(state);
+}
+
+export function localPresence(
+  presence: Presence,
+): Record<string, unknown> | null {
+  return presence.getLocalState();
+}
+
+export function states(presence: Presence): Map<number, Record<string, unknown>> {
+  return presence.getStates() as Map<number, Record<string, unknown>>;
+}
+
+export function destroyPresence(presence: Presence): void {
+  presence.destroy();
+}

package/src/crdt/bytes.ts

@@ -0,0 +1,26 @@
+function toBinary(bytes: Uint8Array): string {
+  let binary = "";
+  const chunk = 0x8000;
+  for (let i = 0; i < bytes.byteLength; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return binary;
+}
+
+/** Browser-safe. Do not use Node `Buffer` — the workspace opens this in the client. */
+export function toBase64(bytes: Uint8Array): string {
+  const view =
+    bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+      ? bytes
+      : bytes.slice();
+  return btoa(toBinary(view));
+}
+
+export function fromBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}

package/src/crdt/connect.ts

@@ -0,0 +1,285 @@
+/// <reference lib="dom" />
+import {
+  applyAwarenessMessage,
+  encodeAwarenessUpdate,
+  encodeSyncUpdate,
+  syncOpenMessages,
+  peekType,
+  readSync,
+  MSG_AWARENESS,
+  MSG_SYNC,
+} from "./protocol";
+import { REMOTE_ORIGIN, createDoc, applyUpdate, encodeState, destroyDoc, type Doc } from "./doc";
+import type { Presence } from "./awareness";
+
+export type SocketHandle = {
+  close: () => void;
+};
+
+/** Minimal constructor so tests can substitute the browser `WebSocket`. */
+export type SocketFactory = (url: string) => WebSocket;
+
+const RECONNECT_MIN_MS = 1000;
+const RECONNECT_MAX_MS = 30_000;
+
+/**
+ * Application close codes (4xxx: bad query, unauthorized, not found, epoch
+ * mismatch), malformed input, and oversized frames end the session. Everything else — the server going away when a
+ * Vercel Function hits its duration cap, network drops, 1011 — retries.
+ */
+export function shouldReconnect(code: number): boolean {
+  return code < 4000 && ![1002, 1007, 1008, 1009].includes(code);
+}
+
+export function nextReconnectDelay(previous: number): number {
+  return Math.min(previous * 2, RECONNECT_MAX_MS);
+}
+
+function withJitter(delay: number): number {
+  return delay + Math.random() * 250;
+}
+
+type ReconnectingSocket = {
+  readonly current: WebSocket | null;
+  close(): void;
+};
+
+/**
+ * Keeps one live socket to `url`, reopening with exponential backoff after
+ * non-application closes (and immediately when the browser comes back
+ * online). `onOpen` runs for every (re)connection so callers resend state.
+ */
+function reconnecting(
+  url: string,
+  handlers: {
+    onOpen: (socket: WebSocket) => void;
+    onMessage: (event: MessageEvent) => void;
+    onStatus?: (status: SyncStatus) => void;
+    createSocket?: SocketFactory;
+  },
+): ReconnectingSocket {
+  const createSocket = handlers.createSocket ?? ((target) => new WebSocket(target));
+  let socket: WebSocket | null = null;
+  let closed = false;
+  let delay = RECONNECT_MIN_MS;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const online = () => {
+    if (closed || socket || !timer) return;
+    clearTimeout(timer);
+    timer = null;
+    connect();
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("online", online);
+  }
+
+  function connect() {
+    const next = createSocket(url);
+    next.binaryType = "arraybuffer";
+    socket = next;
+    next.addEventListener("open", () => {
+      delay = RECONNECT_MIN_MS;
+      handlers.onStatus?.("live");
+      handlers.onOpen(next);
+    });
+    next.addEventListener("message", handlers.onMessage);
+    next.addEventListener("error", () => {
+      handlers.onStatus?.("error");
+    });
+    next.addEventListener("close", (event) => {
+      if (socket === next) socket = null;
+      handlers.onStatus?.("offline");
+      if (closed || !shouldReconnect(event.code)) return;
+      timer = setTimeout(() => {
+        timer = null;
+        connect();
+      }, withJitter(delay));
+      delay = nextReconnectDelay(delay);
+    });
+  }
+  connect();
+
+  return {
+    get current() {
+      return socket;
+    },
+    close() {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+      if (typeof window !== "undefined") {
+        window.removeEventListener("online", online);
+      }
+      socket?.close();
+    },
+  };
+}
+
+function sendBytes(socket: WebSocket, data: Uint8Array): void {
+  const copy = new Uint8Array(data.byteLength);
+  copy.set(data);
+  (socket as unknown as { send: (data: Uint8Array) => void }).send(copy);
+}
+
+function toBytes(data: ArrayBuffer | Blob | string): Promise<Uint8Array> {
+  if (typeof data === "string") {
+    return Promise.resolve(new TextEncoder().encode(data));
+  }
+  if (data instanceof Blob) {
+    return data.arrayBuffer().then((buf) => new Uint8Array(buf));
+  }
+  return Promise.resolve(new Uint8Array(data));
+}
+
+export type SyncControl = {
+  /** `error`: the server could not persist an update; nothing about the lock changed. */
+  type: "locked" | "unlocked" | "reset" | "error" | "schema_incompatible";
+  epoch: number;
+};
+
+export type SyncStatus = "live" | "offline" | "error";
+
+export function connectSync(
+  doc: Doc,
+  url: string,
+  opts?: {
+    onControl?: (msg: SyncControl) => void;
+    canSync?: (candidate: Doc) => boolean;
+    onBlocked?: () => void;
+    onStatus?: (status: SyncStatus) => void;
+    createSocket?: SocketFactory;
+  },
+): SocketHandle {
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    doc.off("update", onUpdate);
+    link.close();
+  };
+  const allowed = (candidate: Doc = doc) => {
+    if (stopped) return false;
+    if (opts?.canSync?.(candidate) === false) {
+      stop();
+      opts.onBlocked?.();
+      return false;
+    }
+    return true;
+  };
+  const link = reconnecting(url, {
+    onStatus: opts?.onStatus,
+    createSocket: opts?.createSocket,
+    // Every (re)open: state vector + local state, so the server fills gaps
+    // from the lost window and takes what was edited offline.
+    onOpen(socket) {
+      if (!allowed()) return;
+      for (const message of syncOpenMessages(doc)) {
+        sendBytes(socket, message);
+      }
+    },
+    onMessage(event) {
+      handleSyncMessage(event);
+    },
+  });
+
+  const onUpdate = (update: Uint8Array, origin: unknown) => {
+    if (origin === REMOTE_ORIGIN || !allowed()) return;
+    const socket = link.current;
+    if (!socket || socket.readyState !== WebSocket.OPEN) return;
+    sendBytes(socket, encodeSyncUpdate(update));
+  };
+  doc.on("update", onUpdate);
+
+  function handleSyncMessage(event: MessageEvent) {
+    if (stopped) return;
+    if (typeof event.data === "string") {
+      try {
+        const parsed = JSON.parse(event.data) as SyncControl;
+        if (
+          parsed &&
+          (parsed.type === "locked" ||
+            parsed.type === "unlocked" ||
+            parsed.type === "reset" ||
+            parsed.type === "error" ||
+            parsed.type === "schema_incompatible")
+        ) {
+          if (parsed.type === "schema_incompatible") stop();
+          opts?.onControl?.(parsed);
+        }
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    void toBytes(event.data).then((bytes) => {
+      if (stopped || peekType(bytes) !== MSG_SYNC) return;
+      if (opts?.canSync) {
+        const candidate = createDoc();
+        try {
+          applyUpdate(candidate, encodeState(doc));
+          readSync(candidate, bytes);
+          if (!allowed(candidate)) return;
+        } finally {
+          destroyDoc(candidate);
+        }
+      }
+      const reply = readSync(doc, bytes);
+      if (!allowed()) return;
+      const socket = link.current;
+      if (reply && socket && socket.readyState === WebSocket.OPEN) {
+        sendBytes(socket, reply);
+      }
+    }).catch(() => {
+      if (stopped) return;
+      stop();
+      opts?.onStatus?.("error");
+    });
+  }
+
+  return {
+    close() {
+      stop();
+    },
+  };
+}
+
+export function connectPresence(
+  presence: Presence,
+  url: string,
+  opts?: { createSocket?: SocketFactory },
+): SocketHandle {
+  const link = reconnecting(url, {
+    createSocket: opts?.createSocket,
+    // Re-announce every known state so peers see us after a reconnect.
+    onOpen(socket) {
+      sendBytes(socket, encodeAwarenessUpdate(presence));
+    },
+    onMessage(event) {
+      void toBytes(event.data).then((bytes) => {
+        if (peekType(bytes) !== MSG_AWARENESS) return;
+        applyAwarenessMessage(presence, bytes);
+      });
+    },
+  });
+
+  const onChange = (
+    { added, updated, removed }: { added: number[]; updated: number[]; removed: number[] },
+    origin: unknown,
+  ) => {
+    if (origin === REMOTE_ORIGIN) return;
+    const socket = link.current;
+    if (!socket || socket.readyState !== WebSocket.OPEN) return;
+    const clients = [...added, ...updated, ...removed];
+    if (clients.length === 0) return;
+    sendBytes(socket, encodeAwarenessUpdate(presence, clients));
+  };
+  presence.on("update", onChange);
+
+  return {
+    close() {
+      presence.off("update", onChange);
+      link.close();
+    },
+  };
+}