@abloatai/ablo 0.36.0 → 0.37.0

package/dist/mutators/undoApply.js

@@ -1,117 +0,0 @@
-/**
- * Conflict-aware replay of undo and redo operations, so undo reverts only your
- * own changes.
- *
- * The undo stack is already per-client: only your local mutator calls record
- * onto it through `UndoScope.record`, and a collaborator's edits arrive as
- * inbound sync deltas that never enter it. This module adds the other half of
- * per-user undo. When replaying a recorded operation, it touches a field only
- * if that field's current value still equals the value this operation
- * established. Undo therefore reverts your change where it still stands and
- * leaves alone any field a collaborator has since overwritten — selective undo
- * applied to a field-level, last-writer-wins model.
- *
- * {@link resolveOps} does the filtering. It takes the operations about to be
- * replayed (`apply` — the inverses on undo, the forwards on redo) and their
- * counterparts (`paired`), which carry the value each operation established: on
- * undo the forwards say what you set, and on redo the inverses say what undo
- * restored. For `update` and `updateMany` operations it drops any field whose
- * live value no longer matches that established value. The `create` and
- * `delete` families are structural and always applied — undoing a create
- * removes the row you added, and undoing a delete restores it.
- *
- * When no collaborator is involved, the live value always equals what you set,
- * so nothing is dropped and single-user undo behaves exactly as before.
- */
-import { deepEqual } from '../transaction/utils/json.js';
-export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
-/**
- * Structural equality for JSON-shaped values — scalars, arrays, and plain
- * objects — ignoring object key order. Re-exported from the package's shared
- * JSON helper so the undo path and your own code can share one implementation.
- */
-export { deepEqual };
-/**
- * Map `id → { field: establishedValue }` from the paired ops. Only update-family
- * ops carry per-field values worth comparing.
- */
-function buildEstablished(paired) {
-    const map = new Map();
-    for (const op of paired) {
-        if (op.kind === 'update') {
-            map.set(op.patch.id, op.patch);
-        }
-        else if (op.kind === 'updateMany') {
-            for (const p of op.patches)
-                map.set(p.id, p);
-        }
-    }
-    return map;
-}
-/** Read the live value of a field from the store's pool, or `undefined`. */
-function readCurrentField(store, id, field) {
-    const model = store.pool.get(id);
-    if (!model)
-        return undefined;
-    const json = model.toJSON?.();
-    return json ? json[field] : undefined;
-}
-/**
- * Keep only the fields whose live value still equals what this op established
- * (`established[field]`). Returns `null` if nothing survives (the whole op is a
- * no-op — every field was superseded by a collaborator).
- */
-function filterStalePatch(store, patch, established) {
-    const out = { id: patch.id };
-    let kept = 0;
-    for (const field of Object.keys(patch)) {
-        if (field === 'id')
-            continue;
-        if (established && field in established) {
-            // Apply only if the field still holds the value we established, meaning no
-            // collaborator has overwritten it since. Otherwise skip it, so the
-            // collaborator's change is left intact.
-            if (deepEqual(readCurrentField(store, patch.id, field), established[field])) {
-                out[field] = patch[field];
-                kept++;
-            }
-        }
-        else {
-            // No paired value to compare against. The recorder always pairs fields,
-            // so this is theoretical; apply to preserve undo functionality.
-            out[field] = patch[field];
-            kept++;
-        }
-    }
-    return kept > 0 ? out : null;
-}
-/**
- * Filter the ops to apply so they don't clobber concurrent collaborator edits.
- * See the module docblock. `last-writer-wins` returns the ops unchanged.
- */
-export function resolveOps(apply, paired, store, policy) {
-    if (policy === 'last-writer-wins')
-        return apply;
-    const established = buildEstablished(paired);
-    const out = [];
-    for (const op of apply) {
-        if (op.kind === 'update') {
-            const filtered = filterStalePatch(store, op.patch, established.get(op.patch.id));
-            if (filtered)
-                out.push({ kind: 'update', modelKey: op.modelKey, patch: filtered });
-        }
-        else if (op.kind === 'updateMany') {
-            const patches = op.patches
-                .map((p) => filterStalePatch(store, p, established.get(p.id)))
-                .filter((p) => p !== null);
-            if (patches.length > 0) {
-                out.push({ kind: 'updateMany', modelKey: op.modelKey, patches });
-            }
-        }
-        else {
-            // create / createMany / delete / deleteMany — structural, applied as-is.
-            out.push(op);
-        }
-    }
-    return out;
-}

package/dist/policy/index.d.ts

@@ -1,21 +0,0 @@
-/**
- * Pluggable conflict resolution.
- *
- * The engine detects a conflict; a policy decides what to do about it. You
- * implement {@link ConflictPolicy} and register it with the engine on your
- * server. The example below allows writes from a cosmetic "linter" writer and
- * defers everything else to {@link defaultPolicy}.
- *
- * ```ts
- * import { type ConflictPolicy, defaultPolicy } from '@abloatai/ablo/policy';
- *
- * export const myPolicy: ConflictPolicy = (ctx) => {
- *   if (ctx.committer.id.startsWith('linter:')) {
- *     return { action: 'allow', note: 'cosmetic writer' };
- *   }
- *   return defaultPolicy(ctx);
- * };
- * ```
- */
-export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../transaction/policy/types.js';
-export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../transaction/policy/types.js';

package/dist/policy/index.js

@@ -1,20 +0,0 @@
-/**
- * Pluggable conflict resolution.
- *
- * The engine detects a conflict; a policy decides what to do about it. You
- * implement {@link ConflictPolicy} and register it with the engine on your
- * server. The example below allows writes from a cosmetic "linter" writer and
- * defers everything else to {@link defaultPolicy}.
- *
- * ```ts
- * import { type ConflictPolicy, defaultPolicy } from '@abloatai/ablo/policy';
- *
- * export const myPolicy: ConflictPolicy = (ctx) => {
- *   if (ctx.committer.id.startsWith('linter:')) {
- *     return { action: 'allow', note: 'cosmetic writer' };
- *   }
- *   return defaultPolicy(ctx);
- * };
- * ```
- */
-export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../transaction/policy/types.js';

package/dist/query/QueryProcessor.d.ts

@@ -1,75 +0,0 @@
-/**
- * Runs in-memory queries over a set of models — filtering by predicate,
- * sorting, paginating, and caching the results. A caller hands
- * {@link QueryProcessor} the candidate models and the query options, and it
- * returns a {@link QueryResult}. It keeps two caches: a string-keyed cache for
- * plain queries, and a structural-identity cache for predicate queries, whose
- * closures cannot be turned into a stable string key.
- */
-import type { Model } from '../Model.js';
-import type { ModelScope } from '../InstanceCache.js';
-export interface QueryOptions<T extends Model> {
-    predicate?: (model: T) => boolean;
-    /** Stable key to distinguish different predicates for the same model type.
-     *  Required when multiple predicate queries exist for the same model — without this,
-     *  they share a cache key and thrash each other's cached result every render. */
-    predicateKey?: string;
-    scope?: ModelScope;
-    orderBy?: keyof T;
-    order?: 'asc' | 'desc';
-    limit?: number;
-    offset?: number;
-    skipCache?: boolean;
-}
-export interface QueryResult<T extends Model> {
-    data: T[];
-    total: number;
-    hasMore: boolean;
-    fromCache?: boolean;
-}
-export declare class QueryProcessor {
-    private cache;
-    private enableCache;
-    private predicateResultCache;
-    constructor(config?: {
-        enableCache?: boolean;
-    });
-    /**
-     * Process query with filtering, sorting, and pagination
-     */
-    processQuery<T extends Model>(models: T[], modelName: string, options?: QueryOptions<T>): QueryResult<T>;
-    /**
-     * Sort models by field
-     */
-    private sortModels;
-    /**
-     * Find first matching model with predicate
-     */
-    findFirst<T extends Model>(models: Generator<T, void, unknown>, predicate: (model: T) => boolean): T | undefined;
-    /**
-     * Count models with optional predicate
-     */
-    countModels<T extends Model>(models: Generator<T, void, unknown>, predicate?: (model: T) => boolean): number;
-    /**
-     * Generate a deterministic cache key from query parameters.
-     * Functions (predicates) are excluded from the key — predicate queries use
-     * the structural identity cache (predicateResultCache) instead of the
-     * string-based cache.
-     */
-    private generateCacheKey;
-    /**
-     * Invalidate cache by pattern
-     */
-    invalidateCache(pattern?: string): void;
-    /**
-     * Clear all cache
-     */
-    clearCache(): void;
-    /**
-     * Get cache stats for debugging
-     */
-    getCacheStats(): {
-        size: number;
-        enabled: boolean;
-    };
-}

package/dist/query/QueryProcessor.js

@@ -1,255 +0,0 @@
-/**
- * Runs in-memory queries over a set of models — filtering by predicate,
- * sorting, paginating, and caching the results. A caller hands
- * {@link QueryProcessor} the candidate models and the query options, and it
- * returns a {@link QueryResult}. It keeps two caches: a string-keyed cache for
- * plain queries, and a structural-identity cache for predicate queries, whose
- * closures cannot be turned into a stable string key.
- */
-/**
- * The default in-memory cache. It keeps a reverse index from model type to the
- * cache keys for that type, so invalidating one model type costs work
- * proportional to that type's keys rather than a scan of the whole cache. A
- * regex fallback still covers the rare pattern that is not a plain model-type
- * match.
- */
-class BasicQueryCache {
-    cache = new Map();
-    // Reverse index: model type -> set of cache keys for that type
-    modelTypeIndex = new Map();
-    get(key) {
-        return this.cache.get(key);
-    }
-    get size() {
-        return this.cache.size;
-    }
-    set(key, data) {
-        this.cache.set(key, data);
-        // Extract model type from cache key (format: "operation:ModelType:options")
-        const modelType = this.extractModelType(key);
-        if (modelType) {
-            if (!this.modelTypeIndex.has(modelType)) {
-                this.modelTypeIndex.set(modelType, new Set());
-            }
-            this.modelTypeIndex.get(modelType).add(key);
-        }
-    }
-    /**
-     * Optimized invalidation - O(k) where k = keys for model type
-     * Supports both exact model type names and regex patterns (fallback)
-     */
-    invalidate(pattern) {
-        if (!pattern) {
-            this.cache.clear();
-            this.modelTypeIndex.clear();
-            return;
-        }
-        // Fast path: Check if pattern is a simple model type match like ".*ModelType.*"
-        const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
-        if (modelType !== undefined) {
-            const keysToDelete = this.modelTypeIndex.get(modelType);
-            if (keysToDelete) {
-                for (const key of keysToDelete) {
-                    this.cache.delete(key);
-                }
-                this.modelTypeIndex.delete(modelType);
-            }
-            return;
-        }
-        // Slow path fallback: regex matching for complex patterns
-        // This should rarely be needed with proper model type patterns
-        const regex = new RegExp(pattern);
-        const keysToDelete = [];
-        for (const key of this.cache.keys()) {
-            if (regex.test(key)) {
-                keysToDelete.push(key);
-            }
-        }
-        // Batch delete to avoid iterator invalidation
-        for (const key of keysToDelete) {
-            this.cache.delete(key);
-            // Clean up index
-            const modelType = this.extractModelType(key);
-            if (modelType) {
-                this.modelTypeIndex.get(modelType)?.delete(key);
-            }
-        }
-    }
-    clear() {
-        this.cache.clear();
-        this.modelTypeIndex.clear();
-    }
-    /**
-     * Extract model type from cache key
-     * Cache key format: "operation:ModelType:options"
-     */
-    extractModelType(key) {
-        // A missing second segment reads as undefined, so `?? null` yields null.
-        return key.split(':')[1] ?? null;
-    }
-}
-export class QueryProcessor {
-    cache;
-    enableCache;
-    // Stable-reference cache for predicate queries. A string cache key cannot
-    // capture a closure, so predicate queries use a separate identity-based
-    // cache keyed on the deterministic part of the query (model name plus
-    // serializable options). Each entry stores the previous result and a
-    // fingerprint of its model ids; when the ids are unchanged, the processor
-    // returns the previous array reference so observers do not re-render.
-    predicateResultCache = new Map();
-    constructor(config = {}) {
-        this.enableCache = config.enableCache ?? true;
-        this.cache = new BasicQueryCache();
-    }
-    /**
-     * Process query with filtering, sorting, and pagination
-     */
-    processQuery(models, modelName, options = {}) {
-        // Generate cache key
-        const cacheKey = this.generateCacheKey('query', modelName, options);
-        // Check string-based cache (non-predicate queries only)
-        if (!options.predicate && !options.skipCache && this.enableCache) {
-            const cached = this.cache.get(cacheKey);
-            if (cached) {
-                return { ...cached, fromCache: true };
-            }
-        }
-        // Apply predicate filter
-        let filtered = options.predicate ? models.filter(options.predicate) : models;
-        // Sort models
-        if (options.orderBy) {
-            filtered = this.sortModels(filtered, options.orderBy, options.order);
-        }
-        const total = filtered.length;
-        // Apply pagination
-        const offset = options.offset || 0;
-        const limit = options.limit || filtered.length;
-        const data = filtered.slice(offset, offset + limit);
-        const result = {
-            data,
-            total,
-            hasMore: offset + limit < total,
-            fromCache: false,
-        };
-        // For predicate queries: compare by structural identity. Return the
-        // previous array reference when the model ids are unchanged, so observers
-        // don't re-render on a structurally identical result.
-        if (options.predicate && this.enableCache) {
-            const ids = data.map((m) => m.id).join(',');
-            const cached = this.predicateResultCache.get(cacheKey);
-            if (cached && cached.ids === ids) {
-                // Structural match — return previous reference for stability
-                return { ...cached.result, fromCache: true };
-            }
-            // New result — store for future comparison
-            this.predicateResultCache.set(cacheKey, { ids, result });
-        }
-        // For non-predicate queries: use the string-based cache.
-        if (!options.predicate && this.enableCache) {
-            this.cache.set(cacheKey, result);
-        }
-        return result;
-    }
-    /**
-     * Sort models by field
-     */
-    sortModels(models, field, order = 'asc') {
-        return [...models].sort((a, b) => {
-            const aVal = a[field];
-            const bVal = b[field];
-            if (aVal === bVal)
-                return 0;
-            if (aVal === null || aVal === undefined)
-                return 1;
-            if (bVal === null || bVal === undefined)
-                return -1;
-            const comparison = aVal < bVal ? -1 : 1;
-            return order === 'asc' ? comparison : -comparison;
-        });
-    }
-    /**
-     * Find first matching model with predicate
-     */
-    findFirst(models, predicate) {
-        for (const model of models) {
-            if (predicate(model)) {
-                return model;
-            }
-        }
-        return undefined;
-    }
-    /**
-     * Count models with optional predicate
-     */
-    countModels(models, predicate) {
-        let count = 0;
-        for (const model of models) {
-            if (!predicate || predicate(model)) {
-                count++;
-            }
-        }
-        return count;
-    }
-    /**
-     * Generate a deterministic cache key from query parameters.
-     * Functions (predicates) are excluded from the key — predicate queries use
-     * the structural identity cache (predicateResultCache) instead of the
-     * string-based cache.
-     */
-    generateCacheKey(operation, modelName, options) {
-        const serializableOptions = {};
-        let hasPredicate = false;
-        for (const [key, value] of Object.entries(options)) {
-            if (typeof value === 'function') {
-                hasPredicate = true;
-                // Mark that this query has a predicate, but use a stable marker
-                // (not Math.random). The actual caching for predicate queries
-                // is handled by predicateResultCache using ID comparison.
-                serializableOptions[key] = `__predicate__`;
-            }
-            else {
-                serializableOptions[key] = value;
-            }
-        }
-        const sortedOptions = JSON.stringify(serializableOptions, Object.keys(serializableOptions).sort());
-        const key = `${operation}:${modelName}:${sortedOptions}`;
-        return hasPredicate ? `pred:${key}` : key;
-    }
-    /**
-     * Invalidate cache by pattern
-     */
-    invalidateCache(pattern) {
-        this.cache.invalidate(pattern);
-        // Also invalidate predicate result cache for this model type
-        if (pattern) {
-            const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
-            if (modelType !== undefined) {
-                for (const key of this.predicateResultCache.keys()) {
-                    if (key.includes(modelType)) {
-                        this.predicateResultCache.delete(key);
-                    }
-                }
-            }
-        }
-        else {
-            this.predicateResultCache.clear();
-        }
-    }
-    /**
-     * Clear all cache
-     */
-    clearCache() {
-        this.cache.clear();
-        this.predicateResultCache.clear();
-    }
-    /**
-     * Get cache stats for debugging
-     */
-    getCacheStats() {
-        return {
-            size: this.cache.size,
-            enabled: this.enableCache,
-        };
-    }
-}

package/dist/query/client.d.ts

@@ -1,64 +0,0 @@
-/**
- * The HTTP client for the sync query endpoint.
- *
- * {@link postQuery} is a small wrapper over `fetch` that POSTs a
- * {@link QueryBatch} as JSON to `/sync/query`, attaches the bearer credential
- * as an `Authorization` header, and parses the response into a typed
- * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
- * every query in the batch comes back with an empty result, so a
- * fire-and-forget caller cannot crash on an unhandled rejection.
- *
- * Higher-level query helpers build on this to issue structured queries without
- * repeating the fetch and error-handling boilerplate.
- */
-import type { QueryBatch, QueryBatchResult } from './types.js';
-import { type RecoveryClass } from '../transaction/errorCodes.js';
-import { type AuthTokenGetter } from '../transaction/auth/credentialSource.js';
-import type { RuntimeContext } from '../RuntimeContext.js';
-export interface PostQueryOptions {
-    /**
-     * Full base URL of the sync server including the `/api` prefix.
-     * The query endpoint is appended as `/sync/query`, so the final
-     * request hits `${baseUrl}/sync/query`.
-     */
-    baseUrl: string;
-    /** Timeout in ms for the fetch request. Default: 30000. */
-    fetchTimeout?: number;
-    /** The owning client's runtime. Defaults to the module-global bridge. */
-    runtime?: RuntimeContext;
-    /**
-     * Live bearer credential getter. Preferred over `capabilityToken` because it
-     * is read per request, so token refreshes propagate without reconstructing
-     * query helpers.
-     */
-    getAuthToken?: AuthTokenGetter;
-    /**
-     * A fixed credential string, for callers that hold only a copied token.
-     * Prefer `getAuthToken`, which is re-read on each request so a refresh takes
-     * effect without rebuilding the client.
-     */
-    capabilityToken?: string;
-    /**
-     * An optional hook that tries to recover from a rejected credential. When a
-     * query comes back with a 401, its {@link RecoveryClass} is passed here: a
-     * return of `'retry'` means a fresh credential has been obtained and the
-     * request is replayed exactly once, while `'stop'` ends the attempt. Because
-     * the replay happens at most once, a wedged credential cannot cause a retry
-     * loop. When this hook is absent, a 401 is logged and returns empty results
-     * like any other failure.
-     */
-    recoverCredential?: (recovery: RecoveryClass) => Promise<'retry' | 'stop'>;
-}
-/**
- * Sends a batch of queries to `/sync/query` and returns the parsed
- * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
- * every query in the batch comes back with an empty result, which keeps a
- * fire-and-forget caller from crashing on an unhandled rejection. A 401 may
- * first be handed to {@link PostQueryOptions.recoverCredential} for a single
- * retry.
- *
- * The response preserves order: `results[i]` corresponds to the query at
- * `queries[i]`, so callers can rely on index alignment to pull typed results
- * out of a multi-query batch.
- */
-export declare function postQuery(options: PostQueryOptions, batch: QueryBatch): Promise<QueryBatchResult>;