@koolbase/react-native 9.2.0 → 10.0.1

package/dist/offline-state.d.ts

@@ -1,97 +0,0 @@
-export declare function recordKey(userId: string, collection: string, recordId: string): string;
-/** A write waiting to be sent. */
-export interface QueuedWrite {
-    id: string;
-    operation: 'insert' | 'update' | 'delete';
-    collection: string;
-    recordId?: string;
-    data?: Record<string, unknown>;
-    /**
-     * The record as the client last saw it, for update and delete.
-     *
-     * Copied in at enqueue time rather than looked up at replay: the record cache
-     * can be evicted or invalidated in between, and a write whose baseline
-     * depends on something else surviving is not durable. From here on the write
-     * is self-contained.
-     */
-    baseline?: Record<string, unknown>;
-    /** The revision that baseline carried, sent so the server can refuse atomically. */
-    baseRevision?: number;
-    retries: number;
-    enqueuedAt: string;
-}
-/**
- * Why a write is waiting for a decision.
- *
- * Kept distinct because they are different situations and an app showing them
- * to someone should say different things. One means two people changed the same
- * thing; the other means we never knew what the change was based on, so there is
- * nothing to compare it against.
- */
-export type ConflictReason = 
-/** The record moved between the change being made and the queue reaching it. */
-'concurrent_modification'
-/**
- * Queued by a version of this SDK that did not record what the change was
- * composed against. It cannot be replayed safely — there is nothing to check
- * it against — so it waits rather than overwriting whatever is there now.
- */
- | 'baseline_unavailable'
-/**
- * The server refused the write for a reason retrying cannot change — the data
- * no longer satisfies the collection's rules, the record is gone, the caller
- * is not permitted, a unique value is taken.
- *
- * Held rather than retried or dropped. Retrying sends identical bytes to
- * identical rules; dropping loses a change the user believes is saved. Neither
- * tells them anything.
- */
- | 'rejected';
-/** A write the server would not apply, held until someone decides. */
-export interface QueuedConflict {
-    reason: ConflictReason;
-    id: string;
-    operation: 'insert' | 'update' | 'delete';
-    collection: string;
-    recordId: string;
-    local?: Record<string, unknown>;
-    baseline?: Record<string, unknown>;
-    server?: Record<string, unknown>;
-    baseRevision?: number;
-    serverRevision?: number;
-    /** What the server said, when it refused for a terminal reason. */
-    message?: string;
-    createdAt: string;
-}
-export interface OfflineState {
-    pending: QueuedWrite[];
-    conflicts: QueuedConflict[];
-}
-export declare class OfflineStateTooLargeError extends Error {
-    constructor(bytes: number);
-}
-export declare function readOfflineState(userId: string): Promise<OfflineState>;
-/**
- * Reads, mutates, and writes the state under the user's lock.
- *
- * Every mutation goes through here. A caller that reads and writes separately
- * reintroduces the race this exists to prevent.
- */
-export declare function mutateOfflineState(userId: string, mutate: (state: OfflineState) => void): Promise<void>;
-/** Adds a write to the queue, under the user's lock. */
-export declare function queueWrite(userId: string, write: Omit<QueuedWrite, 'retries' | 'enqueuedAt'>): Promise<void>;
-/**
- * Moves writes queued by an earlier version into the current state.
- *
- * Runs once, before any replay, and never contacts the network. Migration that
- * depended on connectivity would give the same input two different outcomes
- * depending on whether the device happened to be online at startup — which is
- * how a bug becomes unreproducible.
- *
- * Inserts carry everything they need and simply move across. Updates and
- * deletes do not: they were queued before baselines were recorded, so replaying
- * one would apply it blindly and overwrite whatever changed in the meantime.
- * They are preserved as waiting for a decision instead — the change is not lost,
- * and nothing is written on a guess.
- */
-export declare function migrateLegacyQueue(userId: string): Promise<void>;

package/dist/offline-state.js

@@ -1,200 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OfflineStateTooLargeError = void 0;
-exports.recordKey = recordKey;
-exports.readOfflineState = readOfflineState;
-exports.mutateOfflineState = mutateOfflineState;
-exports.queueWrite = queueWrite;
-exports.migrateLegacyQueue = migrateLegacyQueue;
-const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
-/**
- * The offline system's correctness-critical state: writes waiting to be sent,
- * and writes the server refused because the record moved underneath them.
- *
- * Both live under one key so moving between them is a single write. A conflict
- * recorded without removing the pending write would replay and be refused
- * forever; a pending write removed without recording the conflict would lose a
- * change the user believes is saved. Two keys admit both outcomes.
- *
- * Records are cached separately, per record. Putting them here would let a
- * growing cache push this value past a storage ceiling and make the queue
- * unreadable — losing the correctness-critical state to something incidental.
- */
-const VERSION = 'v1';
-function stateKey(userId) {
-    return `koolbase:${VERSION}:${userId}:offline-state`;
-}
-function recordKey(userId, collection, recordId) {
-    return `koolbase:${VERSION}:${userId}:record:${collection}:${recordId}`;
-}
-const EMPTY = { pending: [], conflicts: [] };
-/**
- * A conservative ceiling, below the lowest per-value limit any supported
- * AsyncStorage implementation imposes.
- *
- * Not a claim about a platform maximum — a boundary that leaves headroom for
- * rewriting and migration. A queue that cannot be written is a queue that
- * silently stops accepting work, so the limit is enforced with an error rather
- * than discovered.
- */
-const MAX_STATE_BYTES = 1000000;
-class OfflineStateTooLargeError extends Error {
-    constructor(bytes) {
-        super(`Offline state is ${bytes} bytes, above the ${MAX_STATE_BYTES} byte limit. ` +
-            'Sync or resolve what is queued before making more offline changes.');
-        this.name = 'OfflineStateTooLargeError';
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-exports.OfflineStateTooLargeError = OfflineStateTooLargeError;
-/**
- * Serialises access per user.
- *
- * A single setItem is one storage operation, but read-modify-write is not: two
- * callers can both read, both modify, and the second write silently discards
- * the first. Two components queueing a write in the same tick is enough. The
- * lock is in-process — one JavaScript runtime is the assumption every React
- * Native app satisfies, and the SDK does not promise more.
- */
-/** UTF-8 byte length, without depending on TextEncoder being present. */
-function byteLength(s) {
-    if (typeof TextEncoder !== 'undefined') {
-        return new TextEncoder().encode(s).length;
-    }
-    let bytes = 0;
-    for (let i = 0; i < s.length; i++) {
-        const c = s.codePointAt(i);
-        if (c > 0xffff)
-            i++; // surrogate pair, counted once
-        bytes += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4;
-    }
-    return bytes;
-}
-const locks = new Map();
-async function withLock(userId, fn) {
-    const previous = locks.get(userId) ?? Promise.resolve();
-    let release = () => { };
-    const next = new Promise((resolve) => { release = resolve; });
-    locks.set(userId, previous.then(() => next));
-    await previous;
-    try {
-        return await fn();
-    }
-    finally {
-        release();
-        if (locks.get(userId) === next)
-            locks.delete(userId);
-    }
-}
-async function readOfflineState(userId) {
-    try {
-        const raw = await async_storage_1.default.getItem(stateKey(userId));
-        if (!raw)
-            return { ...EMPTY, pending: [], conflicts: [] };
-        const parsed = JSON.parse(raw);
-        return { pending: parsed.pending ?? [], conflicts: parsed.conflicts ?? [] };
-    }
-    catch {
-        // Unreadable state is treated as empty rather than throwing: an app that
-        // cannot start is worse than one that has lost a queue it could not read
-        // anyway. The write path's size guard is what keeps this from happening.
-        return { pending: [], conflicts: [] };
-    }
-}
-/**
- * Reads, mutates, and writes the state under the user's lock.
- *
- * Every mutation goes through here. A caller that reads and writes separately
- * reintroduces the race this exists to prevent.
- */
-async function mutateOfflineState(userId, mutate) {
-    await withLock(userId, async () => {
-        const state = await readOfflineState(userId);
-        mutate(state);
-        const serialised = JSON.stringify(state);
-        // Bytes, not characters. String length undercounts anything outside ASCII —
-        // an accented name, any non-Latin script — so a limit measured in
-        // characters permits more than it claims, which is the wrong direction for
-        // a safety boundary. TextEncoder is not guaranteed in every React Native
-        // runtime, so fall back to a byte count computed directly.
-        const bytes = byteLength(serialised);
-        if (bytes > MAX_STATE_BYTES) {
-            throw new OfflineStateTooLargeError(bytes);
-        }
-        await async_storage_1.default.setItem(stateKey(userId), serialised);
-    });
-}
-/** Adds a write to the queue, under the user's lock. */
-async function queueWrite(userId, write) {
-    await mutateOfflineState(userId, (state) => {
-        state.pending.push({
-            ...write,
-            retries: 0,
-            enqueuedAt: new Date().toISOString(),
-        });
-    });
-}
-const LEGACY_QUEUE_VERSION = 'v1';
-function legacyQueueKey(userId) {
-    return `koolbase:${LEGACY_QUEUE_VERSION}:${userId}:write_queue`;
-}
-/**
- * Moves writes queued by an earlier version into the current state.
- *
- * Runs once, before any replay, and never contacts the network. Migration that
- * depended on connectivity would give the same input two different outcomes
- * depending on whether the device happened to be online at startup — which is
- * how a bug becomes unreproducible.
- *
- * Inserts carry everything they need and simply move across. Updates and
- * deletes do not: they were queued before baselines were recorded, so replaying
- * one would apply it blindly and overwrite whatever changed in the meantime.
- * They are preserved as waiting for a decision instead — the change is not lost,
- * and nothing is written on a guess.
- */
-async function migrateLegacyQueue(userId) {
-    const raw = await async_storage_1.default.getItem(legacyQueueKey(userId));
-    if (!raw)
-        return;
-    let legacy = [];
-    try {
-        legacy = JSON.parse(raw);
-    }
-    catch {
-        // Unreadable: nothing recoverable, and leaving the key would retry forever.
-        await async_storage_1.default.removeItem(legacyQueueKey(userId));
-        return;
-    }
-    await mutateOfflineState(userId, (state) => {
-        for (const w of legacy) {
-            const operation = w.type;
-            if (operation === 'insert') {
-                state.pending.push({
-                    id: w.id,
-                    operation: 'insert',
-                    collection: w.collection,
-                    recordId: w.recordId,
-                    data: w.data,
-                    retries: w.retries ?? 0,
-                    enqueuedAt: w.createdAt ?? new Date().toISOString(),
-                });
-                continue;
-            }
-            if (!w.recordId)
-                continue;
-            state.conflicts.push({
-                id: w.id,
-                reason: 'baseline_unavailable',
-                operation,
-                collection: w.collection ?? '',
-                recordId: w.recordId,
-                local: w.data,
-                createdAt: w.createdAt ?? new Date().toISOString(),
-            });
-        }
-    });
-    await async_storage_1.default.removeItem(legacyQueueKey(userId));
-}

package/dist/pending-write.d.ts

@@ -1,47 +0,0 @@
-import { QueuedWrite } from './offline-state';
-/**
- * A change made offline, waiting to be sent.
- *
- * The counterpart to KoolbaseConflict, one step earlier in the lifecycle: a
- * conflict is a write the server refused; a pending write is one the server has
- * not seen yet. Both are durable state an app should surface — a queue nobody
- * can see accumulates invisibly, and the changes it holds feel saved to the
- * user while existing only on this device.
- *
- * The case that makes this API matter: logout. Queues are per-user and survive
- * logout by design, so a user signing out with pending writes walks away
- * believing their edits saved — and they sync whenever that user next logs in
- * on this device, which may be never. Warn before logout:
- *
- * ```ts
- * const pending = await Koolbase.db.pendingWrites();
- * if (pending.length > 0) {
- *   // "You have 3 unsynced changes. Sync now, or they wait until you
- *   //  next sign in on this device."
- * }
- * ```
- *
- * This is a snapshot, not a live handle — re-read after a sync. Per-user:
- * another account's queue on this device is not visible here.
- */
-export interface PendingWrite {
-    id: string;
-    operation: 'insert' | 'update' | 'delete';
-    collection: string;
-    /** Absent for an insert the server has not yet assigned. */
-    recordId?: string;
-    /** What the user changed. Absent for a delete. */
-    data?: Record<string, unknown>;
-    enqueuedAt: string;
-    /** Failed send attempts so far. A count, not a policy — nothing drops it. */
-    attempts: number;
-}
-/**
- * Maps the stored write to its public shape, field by field.
- *
- * Deliberately not a spread: the stored write carries baseline and baseRevision
- * — replay mechanics, not contract. A spread would leak whatever the storage
- * shape grows next; naming each field means new internals stay internal until
- * someone chooses otherwise.
- */
-export declare function toPendingWrite(w: QueuedWrite): PendingWrite;

package/dist/pending-write.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toPendingWrite = toPendingWrite;
-/**
- * Maps the stored write to its public shape, field by field.
- *
- * Deliberately not a spread: the stored write carries baseline and baseRevision
- * — replay mechanics, not contract. A spread would leak whatever the storage
- * shape grows next; naming each field means new internals stay internal until
- * someone chooses otherwise.
- */
-function toPendingWrite(w) {
-    return {
-        id: w.id,
-        operation: w.operation,
-        collection: w.collection,
-        recordId: w.recordId,
-        data: w.data,
-        enqueuedAt: w.enqueuedAt,
-        attempts: w.retries,
-    };
-}

package/dist/realtime.d.ts

@@ -1,44 +0,0 @@
-import { KoolbaseConfig, RealtimeCallback } from './types';
-type TokenProvider = () => Promise<string | null>;
-export declare class KoolbaseRealtime {
-    private config;
-    private getToken;
-    private ws;
-    private projectId;
-    private listeners;
-    private reconnectAttempts;
-    private reconnectTimer;
-    private connecting;
-    /**
-     * Identifies whose cache a seen record belongs in.
-     *
-     * The record cache is keyed by user, so without this a watched record would
-     * be filed under the wrong key — or under 'anonymous', which is worse than
-     * not caching at all: a baseline stored where it will never be read.
-     */
-    private getUserId?;
-    constructor(config: KoolbaseConfig, getToken: TokenProvider, getUserId?: () => string | null);
-    /** Files a record seen over the socket, if we know whose it is. */
-    private cacheSeenRecord;
-    private forgetSeenRecord;
-    subscribe(collection: string, callback: RealtimeCallback): () => void;
-    private connect;
-    private sendSubscribe;
-    private sendUnsubscribe;
-    /**
-     * Reconnects with backoff, rather than every three seconds forever.
-     *
-     * A fixed interval is fine while a connection is merely interrupted and
-     * costly when it is not: a device with no network, a wrong URL, or a session
-     * the server will not accept retried indefinitely, draining battery and data
-     * the user cannot see or stop.
-     *
-     * Doubling from three seconds to a minute keeps a brief interruption
-     * recovering quickly while a lasting one settles into an interval that costs
-     * almost nothing. The counter resets when a connection opens, so a flaky link
-     * does not accumulate delay.
-     */
-    private scheduleReconnect;
-    disconnect(): void;
-}
-export {};

package/dist/realtime.js

@@ -1,195 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseRealtime = void 0;
-const cache_store_1 = require("./cache-store");
-const record_1 = require("./record");
-const EVENT_TYPE_MAP = {
-    'db.record.created': 'created',
-    'db.record.updated': 'updated',
-    'db.record.deleted': 'deleted',
-};
-function projectIdFromToken(token) {
-    try {
-        const part = token.split('.')[1];
-        if (!part)
-            return null;
-        const b64 = part.replace(/-/g, '+').replace(/_/g, '/');
-        const g = globalThis;
-        let json;
-        if (typeof g.atob === 'function') {
-            const bin = g.atob(b64);
-            json = decodeURIComponent(bin.split('').map((c) => '%' + c.charCodeAt(0).toString(16).padStart(2, '0')).join(''));
-        }
-        else if (g.Buffer) {
-            json = g.Buffer.from(b64, 'base64').toString('utf8');
-        }
-        else {
-            return null;
-        }
-        return JSON.parse(json).project_id ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-class KoolbaseRealtime {
-    constructor(config, getToken, getUserId) {
-        this.ws = null;
-        this.projectId = null;
-        this.listeners = new Map();
-        this.reconnectAttempts = 0;
-        this.reconnectTimer = null;
-        this.connecting = false;
-        this.config = config;
-        this.getToken = getToken;
-        this.getUserId = getUserId;
-    }
-    /** Files a record seen over the socket, if we know whose it is. */
-    async cacheSeenRecord(collection, record) {
-        const userId = this.getUserId?.();
-        if (!userId)
-            return;
-        await (0, cache_store_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
-    }
-    async forgetSeenRecord(recordId) {
-        const userId = this.getUserId?.();
-        if (!userId)
-            return;
-        await (0, cache_store_1.removeCachedRecord)(userId, recordId);
-    }
-    subscribe(collection, callback) {
-        if (!this.listeners.has(collection))
-            this.listeners.set(collection, []);
-        this.listeners.get(collection).push(callback);
-        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-            this.sendSubscribe(collection);
-        }
-        else {
-            void this.connect();
-        }
-        return () => {
-            const callbacks = this.listeners.get(collection) ?? [];
-            const i = callbacks.indexOf(callback);
-            if (i > -1)
-                callbacks.splice(i, 1);
-            if (callbacks.length === 0) {
-                this.listeners.delete(collection);
-                this.sendUnsubscribe(collection);
-            }
-        };
-    }
-    async connect() {
-        if (this.connecting)
-            return;
-        if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING))
-            return;
-        const token = await this.getToken();
-        if (!token) {
-            this.scheduleReconnect(); // sign-in may be in flight
-            return;
-        }
-        this.projectId = projectIdFromToken(token);
-        this.connecting = true;
-        const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
-        const ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
-        this.ws = ws;
-        ws.onopen = () => {
-            this.connecting = false;
-            // A connection that opened is the only proof the endpoint and the
-            // credentials are usable, so the backoff resets here rather than on a
-            // close — a flaky link should not accumulate delay.
-            this.reconnectAttempts = 0;
-            for (const collection of this.listeners.keys())
-                this.sendSubscribe(collection); // (re)subscribe all
-        };
-        ws.onmessage = (event) => {
-            let raw;
-            try {
-                raw = JSON.parse(event.data);
-            }
-            catch {
-                return;
-            }
-            const mapped = EVENT_TYPE_MAP[raw?.type];
-            if (!mapped)
-                return; // ignore subscribed / unsubscribed / error / unknown
-            const payload = raw.payload;
-            if (!payload || !payload.collection)
-                return;
-            let msg;
-            if (mapped === 'deleted') {
-                msg = { type: 'deleted', collection: payload.collection, recordId: payload.record_id };
-                // Gone for everyone, so the cached copy is no longer a baseline for
-                // anything. An edit composed against it would be refused at replay
-                // regardless; removing it makes that a local refusal rather than a
-                // round trip.
-                void this.forgetSeenRecord(payload.record_id);
-            }
-            else if (payload.record) {
-                const record = (0, record_1.recordFromWire)(payload.record);
-                msg = { type: mapped, collection: payload.collection, record };
-                // A record seen over the socket is as freshly seen as one fetched, and
-                // a client watching a collection would otherwise hold a stale baseline
-                // while looking at the change. Writes already queued are unaffected:
-                // their baseline was copied in when they were made, so this cannot move
-                // ground beneath them.
-                void this.cacheSeenRecord(payload.collection, record);
-            }
-            else {
-                return;
-            }
-            (this.listeners.get(payload.collection) ?? []).forEach((cb) => cb(msg));
-        };
-        ws.onclose = () => {
-            this.connecting = false;
-            if (this.ws === ws)
-                this.ws = null;
-            this.scheduleReconnect();
-        };
-        ws.onerror = () => { };
-    }
-    sendSubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
-    }
-    sendUnsubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
-    }
-    /**
-     * Reconnects with backoff, rather than every three seconds forever.
-     *
-     * A fixed interval is fine while a connection is merely interrupted and
-     * costly when it is not: a device with no network, a wrong URL, or a session
-     * the server will not accept retried indefinitely, draining battery and data
-     * the user cannot see or stop.
-     *
-     * Doubling from three seconds to a minute keeps a brief interruption
-     * recovering quickly while a lasting one settles into an interval that costs
-     * almost nothing. The counter resets when a connection opens, so a flaky link
-     * does not accumulate delay.
-     */
-    scheduleReconnect() {
-        if (this.listeners.size === 0 || this.reconnectTimer)
-            return;
-        const delay = Math.min(3000 * Math.pow(2, this.reconnectAttempts), 60000);
-        this.reconnectAttempts += 1;
-        this.reconnectTimer = setTimeout(() => {
-            this.reconnectTimer = null;
-            void this.connect();
-        }, delay);
-    }
-    disconnect() {
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = null;
-        }
-        this.ws?.close();
-        this.ws = null;
-        this.projectId = null;
-        this.listeners.clear();
-    }
-}
-exports.KoolbaseRealtime = KoolbaseRealtime;

package/dist/record.d.ts

@@ -1,2 +0,0 @@
-import { KoolbaseRecord } from './types';
-export declare function recordFromWire(raw: Record<string, unknown>): KoolbaseRecord;

package/dist/record.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.recordFromWire = recordFromWire;
-// Converts the flat public wire shape into a KoolbaseRecord.
-// Server sends: { $id, $createdAt, $updatedAt, $collection, $createdBy?, ...fields }
-function recordFromWire(raw) {
-    const data = {};
-    for (const key of Object.keys(raw)) {
-        if (!key.startsWith('$'))
-            data[key] = raw[key];
-    }
-    return {
-        id: raw['$id'],
-        collection: raw['$collection'],
-        createdBy: raw['$createdBy'],
-        data,
-        createdAt: raw['$createdAt'],
-        updatedAt: raw['$updatedAt'],
-        revision: typeof raw['$revision'] === 'number'
-            ? raw['$revision']
-            : undefined,
-    };
-}