@anfenn/dync 1.0.0

package/src/storage/sqlite/helpers.ts

@@ -0,0 +1,144 @@
+import type { SQLiteCollectionState, SQLiteCondition } from './types';
+
+export const SQLITE_SCHEMA_VERSION_STATE_KEY = 'sqlite_schema_version';
+export const DEFAULT_STREAM_BATCH_SIZE = 200;
+
+export const createDefaultState = <T>(): SQLiteCollectionState<T> => ({
+    sqlConditions: [],
+    jsPredicate: undefined,
+    orderBy: undefined,
+    reverse: false,
+    offset: 0,
+    limit: undefined,
+    distinct: false,
+});
+
+export interface SQLiteBuiltQuery {
+    whereClause: string;
+    parameters: unknown[];
+}
+
+export const buildWhereClause = (conditions: SQLiteCondition[]): SQLiteBuiltQuery => {
+    if (conditions.length === 0) {
+        return { whereClause: '', parameters: [] };
+    }
+
+    const clauses: string[] = [];
+    const parameters: unknown[] = [];
+
+    for (const condition of conditions) {
+        const built = buildCondition(condition);
+        clauses.push(built.clause);
+        parameters.push(...built.parameters);
+    }
+
+    return {
+        whereClause: `WHERE ${clauses.join(' AND ')}`,
+        parameters,
+    };
+};
+
+interface BuiltCondition {
+    clause: string;
+    parameters: unknown[];
+}
+
+const buildCondition = (condition: SQLiteCondition): BuiltCondition => {
+    // Handle 'or' condition first since it doesn't have a column property
+    if (condition.type === 'or') {
+        if (condition.conditions.length === 0) {
+            return { clause: '0 = 1', parameters: [] };
+        }
+        const subClauses: string[] = [];
+        const subParams: unknown[] = [];
+        for (const sub of condition.conditions) {
+            const built = buildCondition(sub);
+            subClauses.push(built.clause);
+            subParams.push(...built.parameters);
+        }
+        return { clause: `(${subClauses.join(' OR ')})`, parameters: subParams };
+    }
+
+    // Handle compound equals (multiple columns ANDed together)
+    if (condition.type === 'compoundEquals') {
+        const clauses = condition.columns.map((col) => `${quoteIdentifier(col)} = ?`);
+        return { clause: `(${clauses.join(' AND ')})`, parameters: condition.values };
+    }
+
+    const col = quoteIdentifier(condition.column);
+
+    switch (condition.type) {
+        case 'equals': {
+            if (condition.caseInsensitive) {
+                return { clause: `LOWER(${col}) = LOWER(?)`, parameters: [condition.value] };
+            }
+            return { clause: `${col} = ?`, parameters: [condition.value] };
+        }
+
+        case 'comparison': {
+            return { clause: `${col} ${condition.op} ?`, parameters: [condition.value] };
+        }
+
+        case 'between': {
+            const lowerOp = condition.includeLower ? '>=' : '>';
+            const upperOp = condition.includeUpper ? '<=' : '<';
+            return {
+                clause: `(${col} ${lowerOp} ? AND ${col} ${upperOp} ?)`,
+                parameters: [condition.lower, condition.upper],
+            };
+        }
+
+        case 'in': {
+            if (condition.values.length === 0) {
+                // No values = no matches
+                return { clause: '0 = 1', parameters: [] };
+            }
+            const placeholders = condition.values.map(() => '?').join(', ');
+            if (condition.caseInsensitive) {
+                return {
+                    clause: `LOWER(${col}) IN (${condition.values.map(() => 'LOWER(?)').join(', ')})`,
+                    parameters: condition.values,
+                };
+            }
+            return { clause: `${col} IN (${placeholders})`, parameters: condition.values };
+        }
+
+        case 'notIn': {
+            if (condition.values.length === 0) {
+                // No exclusions = all match
+                return { clause: '1 = 1', parameters: [] };
+            }
+            const placeholders = condition.values.map(() => '?').join(', ');
+            return { clause: `${col} NOT IN (${placeholders})`, parameters: condition.values };
+        }
+
+        case 'like': {
+            if (condition.caseInsensitive) {
+                return { clause: `LOWER(${col}) LIKE LOWER(?)`, parameters: [condition.pattern] };
+            }
+            return { clause: `${col} LIKE ?`, parameters: [condition.pattern] };
+        }
+    }
+};
+
+export const cloneValue = <T>(value: T): T => {
+    if (typeof globalThis.structuredClone === 'function') {
+        return globalThis.structuredClone(value);
+    }
+    return JSON.parse(JSON.stringify(value ?? null)) as T;
+};
+
+export const quoteIdentifier = (name: string): string => `"${name.replace(/"/g, '""')}"`;
+
+export const normalizeComparableValue = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeComparableValue(entry));
+    }
+    if (value instanceof Date) {
+        return value.valueOf();
+    }
+    if (value === undefined) {
+        return null;
+    }
+    return value;
+};

package/src/storage/sqlite/index.ts

@@ -0,0 +1,11 @@
+export * from './types';
+export * from './helpers';
+export * from './SQLiteCollection';
+export * from './SQLiteWhereClause';
+export * from './SQLiteTable';
+export * from './SqliteQueryContext';
+export * from './SQLiteAdapter';
+
+// Drivers
+export { CapacitorSQLiteDriver } from './drivers/CapacitorSQLiteDriver';
+export { CapacitorFastSqlDriver, type FastSqlDriverOptions } from './drivers/CapacitorFastSqlDriver';

package/src/storage/sqlite/schema.ts

@@ -0,0 +1,44 @@
+export type TableSchemaDefinition = string | SQLiteTableDefinition;
+
+export interface SQLiteTableDefinition {
+    columns: Record<string, SQLiteColumnDefinition>;
+    indexes?: SQLiteIndexDefinition[];
+    tableConstraints?: string[];
+    withoutRowId?: boolean;
+    strict?: boolean;
+}
+
+export interface SQLiteColumnDefinition {
+    type?: string;
+    length?: number;
+    nullable?: boolean;
+    unique?: boolean;
+    default?: SQLiteDefaultValue;
+    check?: string;
+    references?: SQLiteForeignKeyReference | string;
+    collate?: string;
+    generatedAlwaysAs?: string;
+    stored?: boolean;
+    constraints?: string[];
+}
+
+export type SQLiteDefaultValue = string | number | boolean | null;
+
+export interface SQLiteForeignKeyReference {
+    table: string;
+    column?: string;
+    onDelete?: SQLiteForeignKeyAction;
+    onUpdate?: SQLiteForeignKeyAction;
+    match?: string;
+}
+
+export type SQLiteForeignKeyAction = 'SET NULL' | 'SET DEFAULT' | 'RESTRICT' | 'NO ACTION' | 'CASCADE';
+
+export interface SQLiteIndexDefinition {
+    name?: string;
+    columns: string[];
+    unique?: boolean;
+    where?: string;
+    collate?: string;
+    orders?: Array<'ASC' | 'DESC'>;
+}

package/src/storage/sqlite/types.ts

@@ -0,0 +1,164 @@
+import type { SQLiteColumnDefinition, SQLiteTableDefinition } from './schema';
+
+export interface SQLiteAdapterOptions {
+    debug?: boolean | ((statement: string, parameters?: any[]) => void);
+}
+
+export interface SQLiteColumnSchema extends SQLiteColumnDefinition {
+    name: string;
+}
+
+export interface SQLiteNormalizedTableDefinition extends SQLiteTableDefinition {
+    name: string;
+    columns: Record<string, SQLiteColumnSchema>;
+    source: 'dexie' | 'structured';
+}
+
+export interface SQLiteTableSchemaMetadata {
+    name: string;
+    definition: SQLiteNormalizedTableDefinition;
+}
+
+export type SQLiteComparisonOp = '=' | '!=' | '>' | '>=' | '<' | '<=';
+
+export interface SQLiteConditionEquals {
+    type: 'equals';
+    column: string;
+    value: unknown;
+    caseInsensitive?: boolean;
+}
+
+export interface SQLiteConditionComparison {
+    type: 'comparison';
+    column: string;
+    op: SQLiteComparisonOp;
+    value: unknown;
+}
+
+export interface SQLiteConditionBetween {
+    type: 'between';
+    column: string;
+    lower: unknown;
+    upper: unknown;
+    includeLower: boolean;
+    includeUpper: boolean;
+}
+
+export interface SQLiteConditionIn {
+    type: 'in';
+    column: string;
+    values: unknown[];
+    caseInsensitive?: boolean;
+}
+
+export interface SQLiteConditionNotIn {
+    type: 'notIn';
+    column: string;
+    values: unknown[];
+}
+
+export interface SQLiteConditionLike {
+    type: 'like';
+    column: string;
+    pattern: string;
+    caseInsensitive?: boolean;
+}
+
+export interface SQLiteConditionOr {
+    type: 'or';
+    conditions: SQLiteCondition[];
+}
+
+export interface SQLiteConditionCompoundEquals {
+    type: 'compoundEquals';
+    columns: string[];
+    values: unknown[];
+}
+
+export type SQLiteCondition =
+    | SQLiteConditionEquals
+    | SQLiteConditionComparison
+    | SQLiteConditionBetween
+    | SQLiteConditionIn
+    | SQLiteConditionNotIn
+    | SQLiteConditionLike
+    | SQLiteConditionOr
+    | SQLiteConditionCompoundEquals;
+
+export interface SQLiteCollectionState<T> {
+    /** SQL-expressible WHERE conditions (ANDed together) */
+    sqlConditions: SQLiteCondition[];
+    /** JavaScript predicate for conditions that can't be expressed in SQL (e.g., arbitrary filter functions) */
+    jsPredicate?: (record: T, key: string, index: number) => boolean;
+    orderBy?: { index: string | string[]; direction: 'asc' | 'desc' };
+    reverse: boolean;
+    offset: number;
+    limit?: number;
+    distinct: boolean;
+}
+
+export interface TableEntry<T> {
+    key: string;
+    value: T;
+}
+
+export interface SQLiteOrderByOptions {
+    index: string | string[];
+    direction: 'asc' | 'desc';
+}
+
+export interface SQLiteIterateEntriesOptions {
+    orderBy?: SQLiteOrderByOptions;
+    chunkSize?: number;
+}
+
+export interface SQLiteRunResult {
+    changes?: number;
+    lastId?: number;
+}
+
+export interface SQLiteQueryResult {
+    columns?: string[];
+    values?: any[][];
+}
+
+export interface SQLiteDatabaseDriver {
+    readonly type: string;
+    readonly name: string;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    execute(statement: string): Promise<void>;
+    run(statement: string, values?: any[]): Promise<SQLiteRunResult>;
+    query(statement: string, values?: any[]): Promise<SQLiteQueryResult>;
+}
+
+export type SQLiteMigrationDirection = 'upgrade' | 'downgrade';
+
+export interface SQLiteMigrationContext {
+    direction: SQLiteMigrationDirection;
+    fromVersion: number;
+    toVersion: number;
+    execute: (statement: string) => Promise<void>;
+    run: (statement: string, values?: any[]) => Promise<SQLiteRunResult>;
+    query: (statement: string, values?: any[]) => Promise<SQLiteQueryResult>;
+}
+
+export type SQLiteMigrationHandler = (context: SQLiteMigrationContext) => Promise<void> | void;
+
+export interface SQLiteVersionMigration {
+    upgrade?: SQLiteMigrationHandler;
+    downgrade?: SQLiteMigrationHandler;
+}
+
+export interface SQLiteVersionConfigurator {
+    upgrade(handler: SQLiteMigrationHandler): void;
+    downgrade(handler: SQLiteMigrationHandler): void;
+}
+
+export interface SQLiteSchemaDefinitionOptions {
+    migrations?: SQLiteVersionMigration;
+}
+
+export interface StorageSchemaDefinitionOptions {
+    sqlite?: SQLiteSchemaDefinitionOptions;
+}

package/src/storage/types.ts

@@ -0,0 +1,112 @@
+import type { DexieQueryContext } from './dexie/DexieQueryContext';
+import type { MemoryQueryContext } from './memory/MemoryQueryContext';
+import type { TableSchemaDefinition } from './sqlite/schema';
+import type { StorageSchemaDefinitionOptions } from './sqlite/types';
+import type { SqliteQueryContext } from './sqlite/SqliteQueryContext';
+
+export type TransactionMode = 'r' | 'rw';
+
+export interface StorageAdapter {
+    readonly type: string;
+    readonly name: string;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    delete(): Promise<void>;
+    defineSchema(version: number, schema: Record<string, TableSchemaDefinition>, options?: StorageSchemaDefinitionOptions): void;
+    table<T = any>(name: string): StorageTable<T>;
+    transaction<T>(mode: TransactionMode, tableNames: string[], callback: (context: StorageTransactionContext) => Promise<T>): Promise<T>;
+    query<R>(callback: (ctx: DexieQueryContext | SqliteQueryContext | MemoryQueryContext) => Promise<R>): Promise<R>;
+}
+
+export interface StorageTransactionContext {
+    tables: Record<string, StorageTable<any>>;
+}
+
+export interface StorageCollection<T = any> {
+    first(): Promise<T | undefined>;
+    last(): Promise<T | undefined>;
+    each(callback: (item: T, index: number) => void | Promise<void>): Promise<void>;
+    eachKey(callback: (key: unknown, index: number) => void | Promise<void>): Promise<void>;
+    eachPrimaryKey(callback: (key: unknown, index: number) => void | Promise<void>): Promise<void>;
+    eachUniqueKey(callback: (key: unknown, index: number) => void | Promise<void>): Promise<void>;
+    keys(): Promise<unknown[]>;
+    primaryKeys(): Promise<unknown[]>;
+    uniqueKeys(): Promise<unknown[]>;
+    count(): Promise<number>;
+    sortBy(key: string): Promise<T[]>;
+    distinct(): StorageCollection<T>;
+    jsFilter(predicate: (item: T) => boolean): StorageCollection<T>;
+    or(index: string): StorageWhereClause<T>;
+    clone(props?: Record<string, unknown>): StorageCollection<T>;
+    reverse(): StorageCollection<T>;
+    offset(offset: number): StorageCollection<T>;
+    limit(count: number): StorageCollection<T>;
+    toCollection(): StorageCollection<T>;
+    delete(): Promise<number>;
+    modify(changes: Partial<T> | ((item: T) => void | Promise<void>)): Promise<number>;
+    toArray(): Promise<T[]>;
+}
+
+export interface StorageWhereClause<T = any> {
+    equals(value: any): StorageCollection<T>;
+    above(value: any): StorageCollection<T>;
+    aboveOrEqual(value: any): StorageCollection<T>;
+    below(value: any): StorageCollection<T>;
+    belowOrEqual(value: any): StorageCollection<T>;
+    between(lower: any, upper: any, includeLower?: boolean, includeUpper?: boolean): StorageCollection<T>;
+    inAnyRange(ranges: Array<[any, any]>, options?: { includeLower?: boolean; includeUpper?: boolean }): StorageCollection<T>;
+    startsWith(prefix: string): StorageCollection<T>;
+    startsWithIgnoreCase(prefix: string): StorageCollection<T>;
+    startsWithAnyOf(...prefixes: string[]): StorageCollection<T>;
+    startsWithAnyOf(prefixes: string[]): StorageCollection<T>;
+    startsWithAnyOfIgnoreCase(...prefixes: string[]): StorageCollection<T>;
+    startsWithAnyOfIgnoreCase(prefixes: string[]): StorageCollection<T>;
+    equalsIgnoreCase(value: string): StorageCollection<T>;
+    anyOf(...values: any[]): StorageCollection<T>;
+    anyOf(values: any[]): StorageCollection<T>;
+    anyOfIgnoreCase(...values: string[]): StorageCollection<T>;
+    anyOfIgnoreCase(values: string[]): StorageCollection<T>;
+    noneOf(...values: any[]): StorageCollection<T>;
+    noneOf(values: any[]): StorageCollection<T>;
+    notEqual(value: any): StorageCollection<T>;
+}
+
+export interface StorageTable<T = any> {
+    readonly name: string;
+    readonly schema: unknown;
+    readonly hook: unknown;
+    add(item: T): Promise<unknown>;
+    put(item: T): Promise<unknown>;
+    update(key: unknown, changes: Partial<T>): Promise<number>;
+    delete(key: unknown): Promise<void>;
+    clear(): Promise<void>;
+    get(key: unknown): Promise<T | undefined>;
+    toArray(): Promise<T[]>;
+    count(): Promise<number>;
+    bulkAdd(items: T[]): Promise<unknown>;
+    bulkPut(items: T[]): Promise<unknown>;
+    bulkGet(keys: Array<unknown>): Promise<Array<T | undefined>>;
+    bulkUpdate(keysAndChanges: Array<{ key: unknown; changes: Partial<T> }>): Promise<number>;
+    bulkDelete(keys: Array<unknown>): Promise<void>;
+    where(index: string | string[]): StorageWhereClause<T>;
+    orderBy(index: string | string[]): StorageCollection<T>;
+    reverse(): StorageCollection<T>;
+    offset(offset: number): StorageCollection<T>;
+    limit(count: number): StorageCollection<T>;
+    mapToClass(ctor: new (...args: any[]) => any): StorageTable<T>;
+    each(callback: (item: T) => void | Promise<void>): Promise<void>;
+    jsFilter(predicate: (item: T) => boolean): StorageCollection<T>;
+    // The "raw" property exposes the underlying storage operations without Dync sync logic.
+    readonly raw: {
+        add(item: T): Promise<unknown>;
+        put(item: T): Promise<unknown>;
+        update(key: unknown, changes: Partial<T>): Promise<number>;
+        delete(key: unknown): Promise<void>;
+        get(key: unknown): Promise<T | undefined>;
+        bulkAdd(items: T[]): Promise<unknown>;
+        bulkPut(items: T[]): Promise<unknown>;
+        bulkUpdate(keysAndChanges: Array<{ key: unknown; changes: Partial<T> }>): Promise<number>;
+        bulkDelete(keys: Array<unknown>): Promise<void>;
+        clear(): Promise<void>;
+    };
+}

package/src/types.ts

@@ -0,0 +1,186 @@
+import type { Logger, LogLevel } from './logger';
+import type { StorageTable } from './storage/types';
+
+export const SERVER_PK = 'id';
+export const LOCAL_PK = '_localId';
+export const UPDATED_AT = 'updated_at';
+
+export interface SyncedRecord {
+    _localId: string;
+    id?: any;
+    updated_at: string;
+    [k: string]: any;
+}
+
+export interface ApiFunctions {
+    add: (item: any) => Promise<any | undefined>;
+    update: (id: any, changes: any, item: any) => Promise<boolean>;
+    remove: (id: any) => Promise<void>;
+    list: (lastUpdatedAt: Date) => Promise<any[]>;
+    firstLoad?: (lastId: any) => Promise<any[]>;
+}
+
+// ============================================================================
+// Batch Sync Types
+// ============================================================================
+
+/**
+ * Payload for a single change in a batch push request.
+ */
+export interface BatchPushPayload {
+    table: string;
+    action: 'add' | 'update' | 'remove';
+    localId: string;
+    // Server-assigned ID (for update/remove)
+    id?: any;
+    // The data to sync (for add/update)
+    data?: any;
+}
+
+/**
+ * Result for a single change in a batch push response.
+ */
+export interface BatchPushResult {
+    // Client-generated local ID - used to correlate with the request
+    localId: string;
+    success: boolean;
+    // Server-assigned ID (for successful adds)
+    id?: any;
+    // Server-assigned updated_at (for successful adds/updates)
+    updated_at?: string;
+    error?: string;
+}
+
+/**
+ * Result for batch first load operation.
+ */
+export interface BatchFirstLoadResult {
+    // Data grouped by table name
+    data: Record<string, any[]>;
+    // Pagination cursors by table name. Undefined value = table is complete
+    cursors: Record<string, any>;
+    // Whether there's more data to load for any table
+    hasMore: boolean;
+}
+
+/**
+ * Batch sync configuration for
+ */
+export interface BatchSync {
+    /**
+     * Array of table names to sync.
+     */
+    syncTables: string[];
+
+    /**
+     * Push all pending changes to the server in a single request.
+     * @param changes Array of changes to push
+     * @returns Array of results, one per change, correlated by localId
+     */
+    push: (changes: BatchPushPayload[]) => Promise<BatchPushResult[]>;
+
+    /**
+     * Pull changes from server since last sync.
+     * @param since Map of table name to last pulled timestamp
+     * @returns Map of table name to array of changed records
+     */
+    pull: (since: Record<string, Date>) => Promise<Record<string, any[]>>;
+
+    /**
+     * Initial data load for all tables (optional).
+     * @param cursors Map of table name to pagination cursor
+     * @returns Batch first load result with data, cursors, and hasMore flag
+     */
+    firstLoad?: (cursors: Record<string, any>) => Promise<BatchFirstLoadResult>;
+}
+
+export type MissingRemoteRecordStrategy = 'ignore' | 'delete-local-record' | 'insert-remote-record';
+export type ConflictResolutionStrategy = 'local-wins' | 'remote-wins' | 'try-shallow-merge';
+
+export type AfterRemoteAddCallback = (stateKey: string, item: SyncedRecord) => void;
+export type MissingRemoteRecordDuringUpdateCallback = (strategy: MissingRemoteRecordStrategy, item: SyncedRecord) => void;
+
+export interface SyncOptions {
+    syncInterval?: number;
+    logger?: Logger;
+    minLogLevel?: LogLevel;
+    onAfterRemoteAdd?: AfterRemoteAddCallback;
+    missingRemoteRecordDuringUpdateStrategy?: MissingRemoteRecordStrategy;
+    onAfterMissingRemoteRecordDuringUpdate?: MissingRemoteRecordDuringUpdateCallback;
+    conflictResolutionStrategy?: ConflictResolutionStrategy;
+}
+
+export interface FirstLoadProgress {
+    table: string;
+    inserted: number;
+    updated: number;
+    total: number;
+}
+
+export type FirstLoadProgressCallback = (progress: FirstLoadProgress) => void;
+
+export type SyncApi = {
+    enable: (enabled: boolean) => Promise<void>;
+    startFirstLoad: (onProgress?: FirstLoadProgressCallback) => Promise<void>;
+    getState: () => SyncState;
+    resolveConflict: (localId: string, keepLocal: boolean) => Promise<void>;
+    onStateChange: (fn: (state: SyncState) => void) => () => void;
+    onMutation: (fn: (event: MutationEvent) => void) => () => void;
+};
+
+export interface MutationEvent {
+    type: 'add' | 'update' | 'delete' | 'bulkAdd' | 'bulkPut' | 'bulkDelete' | 'clear' | 'put' | 'modify' | 'pull';
+    tableName: string;
+    keys?: unknown[];
+}
+
+export interface PersistedSyncState {
+    firstLoadDone: boolean;
+    pendingChanges: PendingChange[];
+    lastPulled: Record<string, string>;
+    error?: Error;
+    conflicts?: Record<string, Conflict>;
+}
+
+export type SyncStatus = 'disabled' | 'disabling' | 'idle' | 'syncing' | 'error';
+
+export interface SyncState extends PersistedSyncState {
+    status: SyncStatus;
+    hydrated: boolean;
+}
+
+export enum SyncAction {
+    Create = 'create',
+    Update = 'update',
+    Remove = 'remove', // Remote removes are a noop if no record found
+}
+
+export interface PendingChange {
+    action: SyncAction;
+    stateKey: string;
+    localId: string;
+    id?: any;
+    version: number;
+    changes?: any;
+    before?: any;
+    after?: any;
+}
+
+export interface Conflict {
+    stateKey: string;
+    fields: FieldConflict[];
+}
+
+export interface FieldConflict {
+    key: string;
+    localValue: any;
+    remoteValue: any;
+}
+
+export type TableMap<TStoreMap extends Record<string, unknown>> = {
+    [K in keyof TStoreMap]: StorageTable<TStoreMap[K]>;
+};
+
+export type VisibilitySubscription = {
+    remove: () => void;
+};

package/src/wa-sqlite.ts

@@ -0,0 +1,4 @@
+// wa-sqlite Browser SQLite Driver
+// Import this entry point for browser/web builds with SQLite support
+export { WaSqliteDriver, type WaSqliteDriverOptions, type WaSqliteVfsType } from './storage/sqlite/drivers/WaSqliteDriver';
+export type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from './storage/sqlite/types';