@syncular/core 0.0.6-95 → 0.1.0

package/src/utils/realtime-change-index.ts

@@ -0,0 +1,44 @@
+export interface RealtimeChangeScopeEntry<T> {
+  item: T;
+  scopeKeys: readonly string[];
+}
+
+export interface RealtimeChangeScopeIndex<T> {
+  selectForScopeKeys(scopeKeys: Iterable<string>): T[];
+}
+
+export function createRealtimeChangeScopeIndex<T>(
+  entries: readonly RealtimeChangeScopeEntry<T>[]
+): RealtimeChangeScopeIndex<T> {
+  const items = entries.map((entry) => entry.item);
+  const indexesByScopeKey = new Map<string, number[]>();
+
+  for (let index = 0; index < entries.length; index += 1) {
+    const seenScopeKeys = new Set<string>();
+    for (const scopeKey of entries[index]!.scopeKeys) {
+      if (!scopeKey || seenScopeKeys.has(scopeKey)) continue;
+      seenScopeKeys.add(scopeKey);
+      let indexes = indexesByScopeKey.get(scopeKey);
+      if (!indexes) {
+        indexes = [];
+        indexesByScopeKey.set(scopeKey, indexes);
+      }
+      indexes.push(index);
+    }
+  }
+
+  return {
+    selectForScopeKeys(scopeKeys: Iterable<string>): T[] {
+      const selectedIndexes = new Set<number>();
+      for (const scopeKey of scopeKeys) {
+        const indexes = indexesByScopeKey.get(scopeKey);
+        if (!indexes) continue;
+        for (const index of indexes) selectedIndexes.add(index);
+      }
+      if (selectedIndexes.size === 0) return [];
+      return Array.from(selectedIndexes)
+        .sort((a, b) => a - b)
+        .map((index) => items[index]!);
+    },
+  };
+}

package/src/utils/realtime-connection-registry.ts

@@ -0,0 +1,286 @@
+export interface RealtimeConnection {
+  readonly clientId: string;
+  readonly ownerKey: string;
+  readonly isOpen: boolean;
+  sendHeartbeat(): void;
+  close(code?: number, reason?: string): void;
+}
+
+export class RealtimeConnectionRegistry<
+  TConnection extends RealtimeConnection,
+> {
+  private connectionsByOwnerKey = new Map<string, Set<TConnection>>();
+  private connectionsByClientId = new Map<string, Set<TConnection>>();
+  private scopeKeysByOwnerKey = new Map<string, Set<string>>();
+  private connectionsByScopeKey = new Map<string, Set<TConnection>>();
+
+  private readonly heartbeatIntervalMs: number;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private readonly onOwnerDisconnected?: (ownerKey: string) => void;
+
+  constructor(options?: {
+    heartbeatIntervalMs?: number;
+    onOwnerDisconnected?: (ownerKey: string) => void;
+  }) {
+    this.heartbeatIntervalMs = options?.heartbeatIntervalMs ?? 30_000;
+    this.onOwnerDisconnected = options?.onOwnerDisconnected;
+  }
+
+  register(
+    connection: TConnection,
+    initialScopeKeys: string[] = []
+  ): () => void {
+    const ownerKey = connection.ownerKey;
+    let ownerConns = this.connectionsByOwnerKey.get(ownerKey);
+    if (!ownerConns) {
+      ownerConns = new Set();
+      this.connectionsByOwnerKey.set(ownerKey, ownerConns);
+    }
+    ownerConns.add(connection);
+
+    let clientConns = this.connectionsByClientId.get(connection.clientId);
+    if (!clientConns) {
+      clientConns = new Set();
+      this.connectionsByClientId.set(connection.clientId, clientConns);
+    }
+    clientConns.add(connection);
+
+    if (!this.scopeKeysByOwnerKey.has(ownerKey)) {
+      this.scopeKeysByOwnerKey.set(ownerKey, new Set(initialScopeKeys));
+    }
+
+    const scopeKeys = this.scopeKeysByOwnerKey.get(ownerKey);
+    if (scopeKeys) {
+      for (const key of scopeKeys) {
+        let scopedConns = this.connectionsByScopeKey.get(key);
+        if (!scopedConns) {
+          scopedConns = new Set();
+          this.connectionsByScopeKey.set(key, scopedConns);
+        }
+        scopedConns.add(connection);
+      }
+    }
+
+    this.ensureHeartbeat();
+    return () => {
+      this.unregister(connection);
+      this.ensureHeartbeat();
+    };
+  }
+
+  updateOwnerScopeKeys(ownerKey: string, scopeKeys: string[]): void {
+    const conns = this.connectionsByOwnerKey.get(ownerKey);
+    if (!conns || conns.size === 0) return;
+
+    const next = new Set(scopeKeys);
+    const prev = this.scopeKeysByOwnerKey.get(ownerKey) ?? new Set<string>();
+
+    if (prev.size === next.size) {
+      let unchanged = true;
+      for (const key of prev) {
+        if (!next.has(key)) {
+          unchanged = false;
+          break;
+        }
+      }
+      if (unchanged) return;
+    }
+
+    this.scopeKeysByOwnerKey.set(ownerKey, next);
+
+    for (const key of prev) {
+      if (next.has(key)) continue;
+      const scopedConns = this.connectionsByScopeKey.get(key);
+      if (!scopedConns) continue;
+      for (const conn of conns) scopedConns.delete(conn);
+      if (scopedConns.size === 0) this.connectionsByScopeKey.delete(key);
+    }
+
+    for (const key of next) {
+      if (prev.has(key)) continue;
+      let scopedConns = this.connectionsByScopeKey.get(key);
+      if (!scopedConns) {
+        scopedConns = new Set();
+        this.connectionsByScopeKey.set(key, scopedConns);
+      }
+      for (const conn of conns) scopedConns.add(conn);
+    }
+  }
+
+  isOwnerSubscribedToScopeKey(ownerKey: string, scopeKey: string): boolean {
+    const scopeKeys = this.scopeKeysByOwnerKey.get(ownerKey);
+    if (!scopeKeys || scopeKeys.size === 0) return false;
+    return scopeKeys.has(scopeKey);
+  }
+
+  getScopeKeysForOwner(ownerKey: string): readonly string[] {
+    const scopeKeys = this.scopeKeysByOwnerKey.get(ownerKey);
+    return scopeKeys ? Array.from(scopeKeys) : [];
+  }
+
+  getConnectionsForOwner(
+    ownerKey: string
+  ): ReadonlySet<TConnection> | undefined {
+    return this.connectionsByOwnerKey.get(ownerKey);
+  }
+
+  getScopedConnectionCount(ownerKey: string): number {
+    return this.connectionsByOwnerKey.get(ownerKey)?.size ?? 0;
+  }
+
+  getConnectionsForClient(
+    clientId: string
+  ): ReadonlySet<TConnection> | undefined {
+    return this.connectionsByClientId.get(clientId);
+  }
+
+  getConnectionCount(clientId: string): number {
+    return this.connectionsByClientId.get(clientId)?.size ?? 0;
+  }
+
+  getTotalConnections(): number {
+    let total = 0;
+    for (const conns of this.connectionsByOwnerKey.values()) {
+      total += conns.size;
+    }
+    return total;
+  }
+
+  forEachConnectionInScopeKeys(
+    scopeKeys: Iterable<string>,
+    visitor: (connection: TConnection) => void,
+    options?: { excludeClientIds?: readonly string[] }
+  ): void {
+    const targets = new Set<TConnection>();
+    for (const key of scopeKeys) {
+      const conns = this.connectionsByScopeKey.get(key);
+      if (!conns) continue;
+      for (const conn of conns) targets.add(conn);
+    }
+
+    const excludedClientIds = new Set(options?.excludeClientIds ?? []);
+    for (const conn of targets) {
+      if (!conn.isOpen) continue;
+      if (excludedClientIds.has(conn.clientId)) continue;
+      visitor(conn);
+    }
+  }
+
+  forEachConnection(visitor: (connection: TConnection) => void): void {
+    for (const conns of this.connectionsByOwnerKey.values()) {
+      for (const conn of conns) {
+        if (!conn.isOpen) continue;
+        visitor(conn);
+      }
+    }
+  }
+
+  closeOwnerConnections(
+    ownerKey: string,
+    code?: number,
+    reason?: string
+  ): void {
+    const conns = this.connectionsByOwnerKey.get(ownerKey);
+    if (!conns) return;
+
+    for (const conn of Array.from(conns)) {
+      conn.close(code, reason);
+      this.unregister(conn);
+    }
+
+    this.ensureHeartbeat();
+  }
+
+  closeClientConnections(
+    clientId: string,
+    code?: number,
+    reason?: string
+  ): void {
+    const conns = this.connectionsByClientId.get(clientId);
+    if (!conns) return;
+
+    for (const conn of Array.from(conns)) {
+      conn.close(code, reason);
+      this.unregister(conn);
+    }
+    this.ensureHeartbeat();
+  }
+
+  closeAll(code?: number, reason?: string): void {
+    for (const conns of this.connectionsByOwnerKey.values()) {
+      for (const conn of Array.from(conns)) {
+        conn.close(code, reason);
+        this.unregister(conn);
+      }
+    }
+    this.ensureHeartbeat();
+  }
+
+  private ensureHeartbeat(): void {
+    if (this.heartbeatIntervalMs <= 0) return;
+
+    const total = this.getTotalConnections();
+    if (total === 0) {
+      if (this.heartbeatTimer) {
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+      }
+      return;
+    }
+
+    if (this.heartbeatTimer) return;
+    this.heartbeatTimer = setInterval(() => {
+      this.sendHeartbeats();
+    }, this.heartbeatIntervalMs);
+  }
+
+  private sendHeartbeats(): void {
+    const closedConnections: TConnection[] = [];
+    for (const conns of this.connectionsByOwnerKey.values()) {
+      for (const conn of conns) {
+        if (!conn.isOpen) {
+          closedConnections.push(conn);
+          continue;
+        }
+        conn.sendHeartbeat();
+      }
+    }
+
+    for (const conn of closedConnections) {
+      this.unregister(conn);
+    }
+
+    this.ensureHeartbeat();
+  }
+
+  private unregister(connection: TConnection): void {
+    const ownerKey = connection.ownerKey;
+
+    const scopeKeys = this.scopeKeysByOwnerKey.get(ownerKey);
+    if (scopeKeys) {
+      for (const key of scopeKeys) {
+        const scopedConns = this.connectionsByScopeKey.get(key);
+        if (!scopedConns) continue;
+        scopedConns.delete(connection);
+        if (scopedConns.size === 0) this.connectionsByScopeKey.delete(key);
+      }
+    }
+
+    const ownerConns = this.connectionsByOwnerKey.get(ownerKey);
+    if (ownerConns) {
+      ownerConns.delete(connection);
+      if (ownerConns.size === 0) {
+        this.connectionsByOwnerKey.delete(ownerKey);
+        this.scopeKeysByOwnerKey.delete(ownerKey);
+        this.onOwnerDisconnected?.(ownerKey);
+      }
+    }
+
+    const clientConns = this.connectionsByClientId.get(connection.clientId);
+    if (!clientConns) return;
+    clientConns.delete(connection);
+    if (clientConns.size === 0) {
+      this.connectionsByClientId.delete(connection.clientId);
+    }
+  }
+}

package/src/utils/table-registry.ts

@@ -0,0 +1,67 @@
+type TableEntry = {
+  table: string;
+  dependsOn?: readonly string[];
+};
+export function registerTableOrThrow(
+  registeredTables: Set<string>,
+  table: string,
+  duplicateTableError: (table: string) => string
+): void {
+  if (registeredTables.has(table)) throw new Error(duplicateTableError(table));
+  registeredTables.add(table);
+}
+export function createTableLookup<T extends TableEntry>(
+  handlers: readonly T[],
+  duplicateTableError: (table: string) => string
+): ReadonlyMap<string, T> {
+  const byTable = new Map<string, T>();
+  for (const handler of handlers) {
+    if (byTable.has(handler.table)) {
+      throw new Error(duplicateTableError(handler.table));
+    }
+    byTable.set(handler.table, handler);
+  }
+  return byTable;
+}
+export function assertKnownTableDependencies<T extends TableEntry>(
+  handlers: readonly T[],
+  byTable: ReadonlyMap<string, T>,
+  unknownDependencyError: (table: string, dependency: string) => string
+): void {
+  for (const handler of handlers) {
+    for (const dependency of handler.dependsOn ?? []) {
+      if (!byTable.has(dependency)) {
+        throw new Error(unknownDependencyError(handler.table, dependency));
+      }
+    }
+  }
+}
+export function topologicallySortTablesByDependencies<T extends TableEntry>(
+  byTable: ReadonlyMap<string, T>,
+  targetTable?: string
+): T[] {
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const sorted: T[] = [];
+  const visit = (table: string) => {
+    if (visited.has(table)) return;
+    if (visiting.has(table)) {
+      throw new Error(
+        `Circular dependency detected involving table "${table}"`
+      );
+    }
+    const handler = byTable.get(table);
+    if (!handler) throw new Error(`Unknown table: ${table}`);
+    visiting.add(table);
+    for (const dependency of handler.dependsOn ?? []) visit(dependency);
+    visiting.delete(table);
+    visited.add(table);
+    sorted.push(handler);
+  };
+  if (targetTable) {
+    visit(targetTable);
+  } else {
+    for (const table of byTable.keys()) visit(table);
+  }
+  return sorted;
+}

package/src/utils/url.ts

@@ -0,0 +1,29 @@
+const ABSOLUTE_URL_SCHEME_REGEX = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+
+const trimTrailingSlashes = (value: string): string =>
+  value.replace(/\/+$/, '');
+
+export function normalizeSyncBaseUrl(url: string): string {
+  const trimmed = trimTrailingSlashes(url.trim());
+  if (!trimmed.endsWith('/sync')) return trimmed;
+  const baseUrl = trimmed.slice(0, -'/sync'.length);
+  return baseUrl.length > 0 ? baseUrl : '/';
+}
+
+export function resolveUrlFromBase(
+  baseUrl: string,
+  path: string,
+  origin?: string
+): string {
+  const normalizedPath = path.replace(/^\/+/, '');
+  const normalizedBaseUrl = trimTrailingSlashes(baseUrl);
+  if (ABSOLUTE_URL_SCHEME_REGEX.test(baseUrl)) {
+    return new URL(
+      normalizedPath,
+      baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`
+    ).toString();
+  }
+  if (origin)
+    return new URL(`${normalizedBaseUrl}/${normalizedPath}`, origin).toString();
+  return `${normalizedBaseUrl}/${normalizedPath}`;
+}

package/src/__tests__/compression.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { gunzipSync } from 'node:zlib';
-import { gzipBytes, gzipBytesToStream } from '../utils';
-
-async function readStream(
-  stream: ReadableStream<Uint8Array>
-): Promise<Uint8Array> {
-  const reader = stream.getReader();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (!value) continue;
-    chunks.push(value);
-    total += value.length;
-  }
-
-  if (chunks.length === 0) return new Uint8Array();
-  if (chunks.length === 1) return chunks[0] ?? new Uint8Array();
-
-  const merged = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    merged.set(chunk, offset);
-    offset += chunk.length;
-  }
-  return merged;
-}
-
-describe('gzipBytes', () => {
-  it('compresses bytes that can be decompressed via gunzip', async () => {
-    const payload = new TextEncoder().encode(
-      'syncular compression test '.repeat(64)
-    );
-    const compressed = await gzipBytes(payload);
-    const decompressed = new Uint8Array(gunzipSync(compressed));
-    expect(decompressed).toEqual(payload);
-  });
-});
-
-describe('gzipBytesToStream', () => {
-  it('returns a gzip stream that round-trips', async () => {
-    const payload = new TextEncoder().encode('stream compression '.repeat(64));
-    const result = await gzipBytesToStream(payload);
-    const compressed = await readStream(result.stream);
-    const decompressed = new Uint8Array(gunzipSync(compressed));
-    expect(decompressed).toEqual(payload);
-    if (typeof result.byteLength === 'number') {
-      expect(result.byteLength).toBe(compressed.length);
-    }
-  });
-});