cry-synced-db-client 0.1.1

package/README.md

@@ -0,0 +1,15 @@
+# synced-db-client
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.5. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/dist/db/DexieDb.d.ts

@@ -0,0 +1,32 @@
+import Dexie from "dexie";
+import type { I_DexieDb, SyncMeta } from "../types/I_DexieDb";
+import type { CollectionConfig } from "../types/CollectionConfig";
+import type { Id, LocalDbEntity } from "../types/DbEntity";
+/**
+ * Implementacija DexieDb interface
+ * Uporablja Dexie za dostop do IndexedDB
+ */
+export declare class DexieDb extends Dexie implements I_DexieDb {
+    private tenant;
+    private collections;
+    private syncMeta;
+    constructor(tenant: string, collectionConfigs: CollectionConfig<any>[]);
+    private getTable;
+    private idToString;
+    save<T extends LocalDbEntity>(collection: string, id: Id, data: Partial<T>): Promise<void>;
+    insert<T extends LocalDbEntity>(collection: string, data: T): Promise<void>;
+    saveMany<T extends LocalDbEntity>(collection: string, items: T[]): Promise<void>;
+    deleteOne(collection: string, id: Id): Promise<void>;
+    saveCollection<T extends LocalDbEntity>(collection: string, data: T[]): Promise<void>;
+    deleteCollection(collection: string): Promise<void>;
+    getById<T extends LocalDbEntity>(collection: string, id: Id): Promise<T | undefined>;
+    getAll<T extends LocalDbEntity>(collection: string): Promise<T[]>;
+    count(collection: string): Promise<number>;
+    getDirty<T extends LocalDbEntity>(collection: string): Promise<T[]>;
+    markDirty(collection: string, id: Id): Promise<void>;
+    markClean(collection: string, id: Id): Promise<void>;
+    getSyncMeta(collection: string): Promise<SyncMeta | undefined>;
+    setSyncMeta(collection: string, lastSyncTs: any): Promise<void>;
+    deleteSyncMeta(collection: string): Promise<void>;
+    getTenant(): string;
+}

package/dist/db/RestProxy.d.ts

@@ -0,0 +1,109 @@
+import type { Timestamp, AggregateOptions } from "mongodb";
+import type { Id } from "../types/DbEntity";
+import type { I_RestInterface, QuerySpec, QueryOpts, GetNewerSpec, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
+/** Progress callback for tracking upload progress */
+export type ProgressCallback = (sentBytes: number, totalBytes: number) => void;
+export interface RestProxyConfig {
+    /** REST endpoint URL */
+    endpoint: string;
+    /** Tenant/database name */
+    tenant: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Default timeout in ms (default: 5000) */
+    defaultTimeoutMs?: number;
+    /** Audit info for requests */
+    audit?: {
+        user?: string;
+        device?: string;
+    };
+    /** Track request timing (lastRequestMs, totalRequestMs) */
+    timeRequests?: boolean;
+    /** Track and print request timing to console (implies timeRequests: true) */
+    timeRequestsPrint?: boolean;
+    /** Callback for upload progress */
+    onProgressCallback?: ProgressCallback;
+    /** Chunk size for progress notifications in bytes (default: 16KB) */
+    progressChunkSize?: number;
+    /** Global abort signal - aborts all requests when triggered */
+    signal?: AbortSignal;
+}
+/**
+ * REST proxy implementing I_RestInterface
+ * Communicates with cry-db server using messagepack encoding
+ *
+ * ## Browser/Node.js/Bun Compatibility
+ *
+ * This implementation uses the native `fetch` API which is available in:
+ * - All modern browsers
+ * - Node.js 18+
+ * - Bun
+ *
+ * ## Performance
+ *
+ * Benchmarked at ~5ms per request (after warmup) on localhost.
+ * Native fetch performs comparably to undici with connection pooling.
+ *
+ * ## Progress Callback Limitations
+ *
+ * Native `fetch` API doesn't support upload progress tracking. Progress callbacks
+ * are simulated by pre-chunking the buffer before sending. This means progress
+ * notifications happen before actual network transmission, not during.
+ *
+ * For real upload progress in browsers, you would need to use XMLHttpRequest
+ * with `upload.onprogress`, but that's not implemented here for simplicity
+ * and cross-platform compatibility.
+ *
+ * ## Dependencies
+ *
+ * - `notepack.io` - MessagePack encoding/decoding (browser compatible)
+ * - `cry-helpers` - Serialization helpers for complex types (Date, ObjectId, etc.)
+ */
+export declare class RestProxy implements I_RestInterface {
+    private endpoint;
+    private tenant;
+    private apiKey?;
+    private defaultTimeoutMs;
+    private audit;
+    private timeRequests;
+    private timeRequestsPrint;
+    private onProgressCallback?;
+    private progressChunkSize;
+    private globalSignal?;
+    private _lastRequestMs;
+    private _totalRequestMs;
+    private _requestCount;
+    constructor(config: RestProxyConfig);
+    /** Set global abort signal */
+    setSignal(signal: AbortSignal | undefined): void;
+    /** Close - no-op for browser fetch (no connection pool) */
+    close(): Promise<void>;
+    /**
+     * Update audit info (e.g., when user logs in)
+     */
+    setAudit(audit: {
+        user?: string;
+        device?: string;
+    }): void;
+    /** Get last request duration in ms */
+    getLastRequestMs(): number;
+    /** Get total request duration in ms */
+    getTotalRequestMs(): number;
+    /** Get total request count */
+    getRequestCount(): number;
+    /** Reset timing stats */
+    resetTimingStats(): void;
+    private restCall;
+    /** Combine multiple abort signals into one */
+    private combineSignals;
+    ping(): Promise<boolean>;
+    findNewer<T>(collection: string, timestamp: Timestamp | number | string | Date, query?: QuerySpec<T>, opts?: QueryOpts): Promise<T[]>;
+    findNewerMany<T>(spec?: GetNewerSpec<T>[]): Promise<Record<string, any[]>>;
+    latestTimestamp(collection: string): Promise<Timestamp | undefined>;
+    latestTimestamps(collections: string[]): Promise<Record<string, Timestamp>>;
+    save<T>(collection: string, update: UpdateSpec<T>, id?: Id): Promise<T>;
+    insert<T>(collection: string, insert: InsertSpec<T>): Promise<T>;
+    deleteOne<T>(collection: string, query: QuerySpec<T>): Promise<T>;
+    aggregate<T>(collection: string, pipeline: object[], opts?: AggregateOptions): Promise<T[]>;
+    upsertBatch<T>(collection: string, batch: BatchSpec<T>): Promise<T[]>;
+}

package/dist/db/SyncedDb.d.ts

@@ -0,0 +1,83 @@
+import type { AggregateOptions } from "mongodb";
+import type { I_SyncedDb, SyncedDbConfig } from "../types/I_SyncedDb";
+import type { QuerySpec, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
+import type { Id, DbEntity } from "../types/DbEntity";
+/**
+ * Glavna implementacija sinhronizirane baze podatkov
+ */
+export declare class SyncedDb implements I_SyncedDb {
+    private tenant;
+    private collections;
+    private dexieDb;
+    private inMemDb;
+    private restInterface;
+    private serverUpdateNotifier?;
+    private restTimeoutMs;
+    private syncTimeoutMs;
+    private debounceMs;
+    private onForcedOffline?;
+    private onSync?;
+    private online;
+    private syncing;
+    private syncLock;
+    private initialized;
+    private pendingChanges;
+    private unsubscribeServerUpdates?;
+    private beforeUnloadHandler?;
+    /** Unikatni ID te instance za detekcijo loopback */
+    private readonly updaterId;
+    constructor(config: SyncedDbConfig);
+    init(): Promise<void>;
+    close(): Promise<void>;
+    isOnline(): boolean;
+    setOnline(online: boolean): void;
+    /**
+     * Prisilno preide v offline stanje in pokliče callback če je nastavljen
+     */
+    private goOffline;
+    private tryGoOnline;
+    /** Ovije promise s timeout za REST operacije */
+    private withRestTimeout;
+    /** Ovije promise s timeout za sync operacije (daljši timeout) */
+    private withSyncTimeout;
+    findById<T extends DbEntity>(collection: string, id: Id): Promise<T | null>;
+    findByIds<T extends DbEntity>(collection: string, ids: Id[]): Promise<T[]>;
+    findOne<T extends DbEntity>(collection: string, query: QuerySpec<T>): Promise<T | null>;
+    find<T extends DbEntity>(collection: string, query?: QuerySpec<T>): Promise<T[]>;
+    aggregate<T>(collection: string, pipeline: object[], opts?: AggregateOptions): Promise<T[]>;
+    save<T extends DbEntity>(collection: string, id: Id, update: Partial<T>): Promise<T>;
+    upsert<T extends DbEntity>(collection: string, query: QuerySpec<T>, update: UpdateSpec<T>): Promise<T>;
+    insert<T extends DbEntity>(collection: string, data: InsertSpec<T>): Promise<T>;
+    deleteOne<T extends DbEntity>(collection: string, id: Id): Promise<T | null>;
+    deleteMany<T extends DbEntity>(collection: string, query: QuerySpec<T>): Promise<number>;
+    hardDeleteOne<T extends DbEntity>(collection: string, id: Id): Promise<T | null>;
+    hardDelete<T extends DbEntity>(collection: string, query: QuerySpec<T>): Promise<number>;
+    ping(timeoutMs?: number): Promise<boolean>;
+    sync(): Promise<void>;
+    isSyncing(): boolean;
+    upsertBatch<T extends DbEntity>(collection: string, batch: BatchSpec<T>): Promise<T[]>;
+    getMemoryCollection<T extends DbEntity>(collection: string): T[];
+    getDebounceMs(): number;
+    private assertCollection;
+    private stripLocalFields;
+    private getPendingKey;
+    private schedulePendingChange;
+    private executePendingChange;
+    private flushAllPendingChanges;
+    private recoverPendingWrites;
+    /**
+     * Sinhronizira eno samo kolekcijo - uporabi se pri handleServerUpdate za updateMany/deleteMany
+     */
+    private syncSingleCollection;
+    /**
+     * Sinhronizira kolekcijo s podatki, ki so že bili pridobljeni s serverja
+     * Vrne statistiko: { conflictsResolved, sentCount }
+     */
+    private syncCollectionWithData;
+    private resolveCollectionConflict;
+    private compareTimestamps;
+    private handleServerUpdate;
+    private handleServerItemUpdate;
+    private getNewFieldsFromServer;
+    private handleServerItemDelete;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import Dexie from "dexie";
+export { Dexie };
+export * from "./types";
+export { SyncedDb } from "./db/SyncedDb";
+export { DexieDb } from "./db/DexieDb";
+export { RestProxy } from "./db/RestProxy";
+export type { RestProxyConfig } from "./db/RestProxy";
+export { resolveConflict } from "./utils/conflictResolution";
+export { filterByQuery, matchesQuery } from "./utils/localQuery";