@syncular/client 0.0.6-95 → 0.1.0

package/src/wasm-bindings/generated-wasm-bindings.d.ts

@@ -0,0 +1,70 @@
+// @generated by packages/client/scripts/generate-wasm-bindings.ts
+// Source: wasm-bindgen declarations in dist/wasm/syncular.d.ts
+// biome-ignore-all lint/suspicious/noExplicitAny: wasm-bindgen emits any for JsValue boundaries.
+
+export class SyncularRustOwnedSqliteClient {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    activeAuthLeasesJson(actor_id: string | null | undefined, now_ms: bigint): string;
+    applyCrdtFieldTextJson(request_json: string): string;
+    applyCrdtFieldYjsUpdateJson(request_json: string): string;
+    applyLeasedMutationJson(operation_json: string, local_row_json?: string | null): Promise<string>;
+    applyLeasedMutationsCommitJson(operations_json: string): string;
+    applyMutationJson(operation_json: string, local_row_json?: string | null): Promise<string>;
+    applyMutationsBatchJson(operations_json: string): string;
+    applyMutationsCommitJson(operations_json: string): string;
+    applyRealtimeSyncPackBytes(bytes: Uint8Array): Promise<string>;
+    applyYjsEnvelopeToPayloadJson(args_json: string): string;
+    applyYjsTextUpdatesJson(args_json: string): string;
+    authLeaseJson(lease_id: string): string;
+    blobCacheStatsJson(): string;
+    blobUploadQueueStatsJson(): string;
+    buildYjsTextUpdateJson(args_json: string): string;
+    clearBlobCache(): void;
+    close(): void;
+    compactCrdtFieldJson(request_json: string): string;
+    compactStorageJson(options_json: string): string;
+    conflictSummariesJson(): Promise<string>;
+    crdtDocumentSnapshotJson(request_json: string): string;
+    crdtUpdateLogJson(request_json: string): string;
+    drainLiveQueryEventsJson(): string;
+    drainRowsChangedEventsJson(): string;
+    encryptionHelperJson(method: string, args_json: string): string;
+    executeSqlValue(sql: string, params: any): any;
+    executeUnsafeSqlValue(sql: string, params: any): any;
+    exportLocalSupportBundleJson(): Promise<string>;
+    forceSubscriptionsBootstrapJson(subscription_ids_json: string): Promise<string>;
+    generatedSchemaStateJson(): string;
+    importLocalSupportBundleJson(bundle_json: string): Promise<string>;
+    isBlobLocal(hash: string): boolean;
+    listTableJson(table: string): Promise<string>;
+    liveQueryDiagnosticsJson(): string;
+    localHealthCheckJson(): Promise<string>;
+    materializeCrdtFieldJson(request_json: string): string;
+    openCrdtFieldJson(request_json: string): string;
+    processBlobUploadQueueJson(retry_now?: boolean | null): Promise<string>;
+    pruneBlobCache(max_bytes: bigint): bigint;
+    recoverSyncPushErrorJson(error_message: string): void;
+    repairLocalHealthJson(request_json: string): Promise<string>;
+    resetLocalSyncStateJson(request_json: string): Promise<string>;
+    resetTransportStats(): void;
+    resolveConflict(id: string, resolution: string): Promise<void>;
+    retrieveBlob(ref_json: string): Promise<Uint8Array>;
+    retryConflictKeepLocal(id: string): Promise<string>;
+    setAbortSignal(signal: any): void;
+    setAuthHeadersJson(headers_json: string): void;
+    setBlobEncryptionJson(config_json: string): void;
+    setEncryptedCrdtJson(config_json: string): void;
+    setFieldEncryptionJson(config_json: string): void;
+    setSubscriptionsJson(subscriptions_json: string): void;
+    snapshotCrdtFieldStateVectorJson(request_json: string): string;
+    storeBlobJson(data: Uint8Array, options_json: string): Promise<string>;
+    subscribeQueryJson(sql: string, params_json: string, tables_json: string, hints_json: string): string;
+    syncOnceJson(): Promise<string>;
+    syncPullJson(): Promise<string>;
+    syncPushJson(): Promise<string>;
+    transportStatsJson(): string;
+    unsubscribeQuery(id: string): void;
+    upsertAuthLeaseJson(lease_json: string): void;
+}

package/src/wasm-bindings/runtime-contract.ts

@@ -0,0 +1,158 @@
+export type { SyncularRustOwnedSqliteClient } from './generated-wasm-bindings';
+
+import type {
+  SyncularRuntimeArtifact,
+  SyncularRuntimeArtifactCandidate,
+  SyncularRuntimeArtifactCatalog,
+} from '../types';
+
+export const SYNCULAR_CLIENT_PACKAGE_NAME = '@syncular/client';
+export const SYNCULAR_CLIENT_PACKAGE_VERSION = '0.1.0';
+export const SYNCULAR_WASM_OUT_NAME = 'syncular';
+export const SYNCULAR_WASM_GLUE_FILE = `${SYNCULAR_WASM_OUT_NAME}.js`;
+export const SYNCULAR_WASM_BINARY_FILE = `${SYNCULAR_WASM_OUT_NAME}_bg.wasm`;
+export const SYNCULAR_WASM_ARTIFACT_FILE = 'syncular-runtime-artifact.json';
+export const SYNCULAR_WASM_ARTIFACT_CATALOG_FILE =
+  'syncular-runtime-artifacts.json';
+export const SYNCULAR_FULL_RUNTIME_FEATURES = [
+  'web-owned-sqlite-core',
+  'web-owned-sqlite',
+  'blobs',
+  'crdt-yjs',
+  'e2ee',
+] as const;
+export const SYNCULAR_CORE_RUNTIME_FEATURES = [
+  'web-owned-sqlite-core',
+] as const;
+
+export type SyncularWasmArtifactVariant = 'full' | 'full-perf' | 'core';
+
+export function getSyncularWasmGlueUrl(): URL {
+  return resolveSyncularWasmAsset(SYNCULAR_WASM_GLUE_FILE);
+}
+
+export function getSyncularWasmUrl(): URL {
+  return resolveSyncularWasmAsset(SYNCULAR_WASM_BINARY_FILE);
+}
+
+export function getSyncularRuntimeArtifactCatalogUrl(): URL {
+  const runtimeUrl = new URL(import.meta.url);
+  const sourceRuntime = runtimeUrl.pathname.endsWith(
+    '/src/wasm-bindings/runtime-contract.ts'
+  );
+  return new URL(
+    sourceRuntime
+      ? `../../dist/${SYNCULAR_WASM_ARTIFACT_CATALOG_FILE}`
+      : `../${SYNCULAR_WASM_ARTIFACT_CATALOG_FILE}`,
+    runtimeUrl
+  );
+}
+
+export function getSyncularRuntimeArtifact(
+  variant: SyncularWasmArtifactVariant = 'full'
+): SyncularRuntimeArtifactCandidate {
+  const dir =
+    variant === 'core'
+      ? 'wasm-core'
+      : variant === 'full-perf'
+        ? 'wasm-perf'
+        : 'wasm';
+  const features =
+    variant === 'core'
+      ? SYNCULAR_CORE_RUNTIME_FEATURES
+      : SYNCULAR_FULL_RUNTIME_FEATURES;
+  return {
+    name: variant,
+    features,
+    wasmGlueUrl: resolveSyncularWasmAsset(SYNCULAR_WASM_GLUE_FILE, dir),
+    wasmUrl: resolveSyncularWasmAsset(SYNCULAR_WASM_BINARY_FILE, dir),
+  };
+}
+
+export function getSyncularPackagedRuntimeArtifacts(): readonly SyncularRuntimeArtifactCandidate[] {
+  return [
+    getSyncularRuntimeArtifact('core'),
+    getSyncularRuntimeArtifact('full'),
+    getSyncularRuntimeArtifact('full-perf'),
+  ];
+}
+
+export function resolveSyncularRuntimeArtifactCatalog(
+  catalog: SyncularRuntimeArtifactCatalog,
+  options: { baseUrl?: string | URL } = {}
+): readonly SyncularRuntimeArtifactCandidate[] {
+  const baseUrl = options.baseUrl ?? getSyncularRuntimeArtifactCatalogUrl();
+  return catalog.artifacts.map((artifact) => ({
+    name: artifact.name,
+    features: artifact.features,
+    wasmGlueUrl: resolveCatalogAssetUrl(artifact.wasmGlueUrl, baseUrl),
+    wasmUrl: resolveCatalogAssetUrl(artifact.wasmUrl, baseUrl),
+  }));
+}
+
+export function selectSyncularRuntimeArtifact(
+  requiredFeatures: readonly string[] = [],
+  artifacts: readonly SyncularRuntimeArtifactCandidate[] = [
+    getSyncularRuntimeArtifact('full'),
+  ]
+): SyncularRuntimeArtifact {
+  const required = new Set(requiredFeatures);
+  for (const artifact of artifacts) {
+    const available = new Set(artifact.features);
+    let compatible = true;
+    for (const feature of required) {
+      if (!available.has(feature)) {
+        compatible = false;
+        break;
+      }
+    }
+    if (compatible) {
+      return {
+        wasmGlueUrl: artifact.wasmGlueUrl,
+        wasmUrl: artifact.wasmUrl,
+      };
+    }
+  }
+
+  throw new Error(
+    `No Syncular Rust runtime artifact satisfies required features: ${[
+      ...required,
+    ].join(', ')}`
+  );
+}
+
+function resolveSyncularWasmAsset(fileName: string, dir = 'wasm'): URL {
+  const runtimeUrl = new URL(import.meta.url);
+  const sourceRuntime = runtimeUrl.pathname.endsWith(
+    '/src/wasm-bindings/runtime-contract.ts'
+  );
+  return new URL(
+    sourceRuntime ? `../../dist/${dir}/${fileName}` : `../${dir}/${fileName}`,
+    runtimeUrl
+  );
+}
+
+function resolveCatalogAssetUrl(
+  value: string,
+  baseUrl: string | URL
+): string | URL {
+  if (isAbsoluteAssetUrl(value)) return value;
+  if (baseUrl instanceof URL) {
+    return new URL(value, new URL('./', baseUrl));
+  }
+  if (hasUrlProtocol(baseUrl)) {
+    return new URL(value, new URL('./', baseUrl)).href;
+  }
+  const baseDir = baseUrl.endsWith('/')
+    ? baseUrl
+    : baseUrl.slice(0, Math.max(0, baseUrl.lastIndexOf('/') + 1));
+  return `${baseDir}${value}`;
+}
+
+function isAbsoluteAssetUrl(value: string): boolean {
+  return value.startsWith('/') || hasUrlProtocol(value);
+}
+
+function hasUrlProtocol(value: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(value);
+}

package/src/wasm-runtime.ts

@@ -0,0 +1,76 @@
+import type {
+  ResolvedSyncularClientConfig,
+  SyncularRustRuntimeInfo,
+} from './types';
+import {
+  getSyncularWasmGlueUrl,
+  getSyncularWasmUrl,
+  type SyncularRustOwnedSqliteClient,
+} from './wasm-bindings/runtime-contract';
+
+export type {
+  SyncularRustOwnedSqliteClient,
+  SyncularWasmArtifactVariant,
+} from './wasm-bindings/runtime-contract';
+export {
+  getSyncularPackagedRuntimeArtifacts,
+  getSyncularRuntimeArtifact,
+  getSyncularRuntimeArtifactCatalogUrl,
+  getSyncularWasmGlueUrl,
+  getSyncularWasmUrl,
+  resolveSyncularRuntimeArtifactCatalog,
+  selectSyncularRuntimeArtifact,
+} from './wasm-bindings/runtime-contract';
+
+export interface SyncularWasmGlue {
+  default(moduleOrPath?: string | URL | Request): Promise<unknown>;
+  syncularRuntimeInfoJson(): string;
+  syncularBuildYjsTextUpdateJson(argsJson: string): string;
+  syncularApplyYjsTextUpdatesJson(argsJson: string): string;
+  syncularApplyYjsEnvelopeToPayloadJson(argsJson: string): string;
+  syncularMaterializeYjsRowJson(argsJson: string): string;
+  syncularEncryptionHelperJson(method: string, argsJson: string): string;
+  openSyncularRustOwnedSqliteClient(
+    config: ResolvedSyncularClientConfig
+  ): Promise<SyncularRustOwnedSqliteClient>;
+}
+
+let modulePromise: Promise<SyncularWasmGlue> | undefined;
+
+export function loadSyncularWasmGlue(): Promise<SyncularWasmGlue> {
+  modulePromise ??= (
+    import(
+      /* @vite-ignore */ getSyncularWasmGlueUrl().href
+    ) as Promise<SyncularWasmGlue>
+  ).catch((error: unknown) => {
+    modulePromise = undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    if (/cannot find module|failed to fetch|not found/i.test(message)) {
+      throw new Error(
+        `Syncular WASM runtime artifact is missing (${message}). ` +
+          'In this repo, build it first: `bun run client:build:wasm` ' +
+          '(or `bun --cwd packages/client build:wasm:dev` for a fast dev ' +
+          'build). In an app, ensure the @syncular/client dist/wasm assets ' +
+          'are served.',
+        { cause: error }
+      );
+    }
+    throw error;
+  });
+  return modulePromise;
+}
+
+export async function getSyncularRustRuntimeInfo(
+  mod?: SyncularWasmGlue | Promise<SyncularWasmGlue>,
+  wasmUrl: string | URL | Request = getSyncularWasmUrl()
+): Promise<SyncularRustRuntimeInfo> {
+  const resolved = await (mod ?? loadSyncularWasmGlue());
+  await resolved.default(wasmUrl);
+  return readSyncularRustRuntimeInfo(resolved);
+}
+
+export function readSyncularRustRuntimeInfo(
+  mod: SyncularWasmGlue
+): SyncularRustRuntimeInfo {
+  return JSON.parse(mod.syncularRuntimeInfoJson()) as SyncularRustRuntimeInfo;
+}