@syncular/client 0.1.2 → 0.2.0

package/dist/content-type.d.ts

@@ -0,0 +1,2 @@
+/** SSP2 body content type (SPEC.md §1.1). */
+export declare const SSP2_CONTENT_TYPE = "application/vnd.syncular.sync.v2";

package/dist/content-type.js

@@ -0,0 +1,2 @@
+/** SSP2 body content type (SPEC.md §1.1). */
+export const SSP2_CONTENT_TYPE = 'application/vnd.syncular.sync.v2';

package/dist/database.d.ts

@@ -1,83 +1,38 @@
-import { type BlobRef, type ColumnCodecDialect, type ColumnCodecSource, type SyncAuthLeaseIssueRequest, type SyncOperation } from '@syncular/core';
-import { type Dialect, Kysely } from 'kysely';
-import { SyncularClientLifecycle, type SyncularClientStatus, type SyncularConflictsClientLike, type SyncularPresenceClientLike } from './client';
-import { type MutationsApi, type MutationsCommitFn } from './mutations';
-import type { CreateSyncularDatabaseOptions, SyncularAuthLeaseRecord, SyncularBlobStoreOptions, SyncularBlobs, SyncularClientEventSink, SyncularClientEventType, SyncularDiagnosticSnapshot, SyncularLiveQueries, SyncularRuntimeClient, SyncularSubscriptionSpec, SyncularSyncRequestOptions, SyncularSyncResult, SyncularTableConfigMap } from './types';
-export interface SyncularDialect extends Dialect, SyncularLiveQueries {
-    destroyLiveQueries(): Promise<void>;
-}
-export interface SyncularDialectOptions {
-    appTables?: readonly string[];
-    tableConfig?: SyncularTableConfigMap;
-    unsafeWrites?: boolean;
-}
-export interface SyncularDatabase<DB> extends SyncularLiveQueries {
-    db: Kysely<DB>;
-    client: SyncularRuntimeClient;
-    dialect: SyncularDialect;
-    mutations: MutationsApi<DB, undefined>;
-    leasedMutations: MutationsApi<DB, undefined>;
-    blobs: SyncularBlobs;
+/**
+ * Storage abstraction (REVISE B3): the client core runs on any SQLite that
+ * implements this minimal synchronous surface. Tests use bun:sqlite
+ * (`./bun-database`); browsers use sqlite-wasm + OPFS (`./wasm-database`).
+ * Methods are synchronous because both backends execute synchronously once
+ * open — only opening a database is async, which lives in the factories.
+ */
+export type SqlValue = string | number | bigint | boolean | Uint8Array | null;
+export type SqlRow = Record<string, SqlValue>;
+export interface ClientDatabase {
+    /** Execute a single statement (no result rows). */
+    exec(sql: string, params?: readonly SqlValue[]): void;
+    /** Execute a single statement and return its rows as objects. */
+    query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     /**
-     * The sync lifecycle owned by this database. It starts automatically while
-     * the database opens (remote mode, unless `lifecycle.autoStart` is false)
-     * and stops on `close()`. Reach for it directly only for advanced control;
-     * `start`/`stop`/`sync` proxy to it.
+     * Run `fn` atomically. Nested calls are savepoints: an inner failure
+     * rolls back only the inner scope.
      */
-    lifecycle: SyncularClientLifecycle;
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    sync(): Promise<SyncularSyncResult>;
-    on<T extends SyncularClientEventType>(event: T, listener: SyncularClientEventSink<T>): () => void;
-    getStatus(): SyncularClientStatus;
-    setSubscriptions(subscriptions: readonly SyncularSubscriptionSpec[]): Promise<void>;
-    resumeFromBackground(options?: SyncularSyncRequestOptions): Promise<SyncularSyncResult>;
-    issueAuthLease(request: SyncAuthLeaseIssueRequest): Promise<SyncularAuthLeaseRecord>;
-    upsertAuthLease(lease: SyncularAuthLeaseRecord): Promise<void>;
-    authLease(leaseId: string): Promise<SyncularAuthLeaseRecord | null>;
-    activeAuthLeases(actorId?: string | null, nowMs?: number): Promise<SyncularAuthLeaseRecord[]>;
-    diagnosticSnapshot(): Promise<SyncularDiagnosticSnapshot>;
-    presence: SyncularPresenceClientLike;
-    conflicts: SyncularConflictsClientLike;
-    close(): Promise<void>;
-}
-export declare function withSyncularSchemaWrites<DB, Result>(database: Pick<SyncularDatabase<DB>, 'client'>, callback: (db: Kysely<any>) => Promise<Result>): Promise<Result>;
-export interface SyncularMutationsMeta {
-    operations: SyncOperation[];
-    localMutations: Array<{
-        table: string;
-        rowId: string;
-        op: 'upsert' | 'delete';
-    }>;
-    clientCommitIds: string[];
-}
-export interface SyncularMutationsOptions {
-    client: Pick<SyncularRuntimeClient, 'applyMutation' | 'applyMutationsBatch' | 'applyMutationsCommit' | 'applyYjsEnvelopeToPayload' | 'executeSql'> & Partial<Pick<SyncularRuntimeClient, 'applyLeasedMutation' | 'applyLeasedMutationsCommit'>>;
-    requireAuthLease?: boolean;
-    codecs?: ColumnCodecSource;
-    codecDialect?: ColumnCodecDialect;
-    idColumn?: string;
-    versionColumn?: string | null;
-    omitColumns?: string[];
-    tableConfig?: SyncularTableConfigMap;
-    readBaseVersion?: (args: {
-        table: string;
-        rowId: string;
-        idColumn: string;
-        versionColumn: string;
-    }) => Promise<number | null>;
-    afterCommit?: (meta: SyncularMutationsMeta) => void | Promise<void>;
+    transaction<T>(fn: () => T): T;
+    /**
+     * Optional sqlite-image capability (SPEC §5.3): expose `bytes` as an
+     * attached read-only database schema named `alias` for the duration of
+     * `fn`, then detach. Presence of this method is what makes the client
+     * advertise `accept` bit 2 (§4.2). MUST be called outside any open
+     * transaction (SQLite cannot ATTACH inside one); `fn` may open its own.
+     */
+    withSqliteImage?<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
+    close(): void;
 }
-export declare function createSyncularDatabase<DB>(options: CreateSyncularDatabaseOptions): Promise<SyncularDatabase<DB>>;
-export declare function createSyncularBlobClient(client: Pick<SyncularRuntimeClient, 'storeBlob' | 'retrieveBlob' | 'isBlobLocal' | 'processBlobUploadQueue' | 'blobUploadQueueStats' | 'blobCacheStats' | 'pruneBlobCache' | 'clearBlobCache'>, hooks?: {
-    limits?: CreateSyncularDatabaseOptions['blobLimits'];
-    diagnostics?: CreateSyncularDatabaseOptions['diagnostics'];
-    afterStore?: (args: {
-        ref: BlobRef;
-        options?: SyncularBlobStoreOptions;
-    }) => void | Promise<void>;
-}): SyncularBlobs;
-export declare function createSyncularDialect(client: SyncularRuntimeClient, options?: SyncularDialectOptions): SyncularDialect;
-export declare function createSyncularMutations<DB>(options: SyncularMutationsOptions): MutationsApi<DB, undefined>;
-export declare function createSyncularCommit<DB>(options: SyncularMutationsOptions): MutationsCommitFn<DB, SyncularMutationsMeta, undefined>;
-//# sourceMappingURL=database.d.ts.map
+/** Attach-schema aliases are code-chosen, never user input — enforce it. */
+export declare function assertImageAlias(alias: string): void;
+/**
+ * Savepoint-based transaction helper shared by database implementations.
+ * `run` executes a parameterless statement.
+ */
+export declare function runTransaction<T>(depthHolder: {
+    depth: number;
+}, run: (sql: string) => void, fn: () => T): T;