@abloatai/ablo 0.36.0 → 0.37.1

package/dist/transactions/mutations/optimisticApply.d.ts

@@ -1,49 +0,0 @@
-/**
- * Local-first apply and rollback bookkeeping for pending mutations.
- *
- * When a change is written before the server confirms it, these functions
- * record it in a ledger and emit an `optimistic:*` event; separate listeners
- * apply the change to the in-memory data and, on rollback, restore the value
- * it replaced. Each function takes the ledger and a small event emitter rather
- * than any larger object, so the rules have no dependencies of their own and
- * can be tested in isolation.
- */
-import type { Model } from '../../Model.js';
-import type { MutationInput, QueuedMutation } from './commitPayload.js';
-/**
- * One tracked optimistic mutation: the live model plus the value it held
- * before the change, kept so a rollback can restore it.
- */
-export interface OptimisticUpdateEntry {
-    model: Model;
-    previousState: MutationInput | null | undefined;
-    transaction: QueuedMutation;
-}
-/**
- * The event emitter these functions use to announce each optimistic change and
- * its rollback. You supply the implementation.
- */
-export interface OptimisticEmitter {
-    emit(event: string, payload: unknown): void;
-}
-/**
- * Record an optimistic create and announce it. There is no prior value to
- * restore, so the rollback pre-image is `null`.
- */
-export declare function applyOptimisticCreate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: QueuedMutation): void;
-/**
- * Record an optimistic update and announce it, keeping the row's prior value so
- * a rollback can put it back.
- */
-export declare function applyOptimisticUpdate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: QueuedMutation): void;
-/**
- * Record an optimistic delete and announce it, keeping the deleted row so a
- * rollback can restore it.
- */
-export declare function applyOptimisticDelete(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: QueuedMutation): void;
-/**
- * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
- * with the saved pre-image so listeners can restore the prior value, then drop
- * the ledger entry. Does nothing if the transaction was never tracked.
- */
-export declare function rollbackOptimistic(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, transaction: QueuedMutation, reason?: string, error?: Error): Promise<void>;

package/dist/transactions/mutations/optimisticApply.js

@@ -1,65 +0,0 @@
-/**
- * Local-first apply and rollback bookkeeping for pending mutations.
- *
- * When a change is written before the server confirms it, these functions
- * record it in a ledger and emit an `optimistic:*` event; separate listeners
- * apply the change to the in-memory data and, on rollback, restore the value
- * it replaced. Each function takes the ledger and a small event emitter rather
- * than any larger object, so the rules have no dependencies of their own and
- * can be tested in isolation.
- */
-/**
- * Record an optimistic create and announce it. There is no prior value to
- * restore, so the rollback pre-image is `null`.
- */
-export function applyOptimisticCreate(optimisticUpdates, emitter, model, transaction) {
-    optimisticUpdates.set(transaction.id, {
-        model,
-        previousState: null,
-        transaction,
-    });
-    emitter.emit('optimistic:create', { model, transaction });
-}
-/**
- * Record an optimistic update and announce it, keeping the row's prior value so
- * a rollback can put it back.
- */
-export function applyOptimisticUpdate(optimisticUpdates, emitter, model, transaction) {
-    optimisticUpdates.set(transaction.id, {
-        model,
-        previousState: transaction.previousData,
-        transaction,
-    });
-    emitter.emit('optimistic:update', { model, transaction });
-}
-/**
- * Record an optimistic delete and announce it, keeping the deleted row so a
- * rollback can restore it.
- */
-export function applyOptimisticDelete(optimisticUpdates, emitter, model, transaction) {
-    optimisticUpdates.set(transaction.id, {
-        model,
-        previousState: transaction.previousData,
-        transaction,
-    });
-    emitter.emit('optimistic:delete', { model, transaction });
-}
-/**
- * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
- * with the saved pre-image so listeners can restore the prior value, then drop
- * the ledger entry. Does nothing if the transaction was never tracked.
- */
-export function rollbackOptimistic(optimisticUpdates, emitter, transaction, reason, error) {
-    const optimistic = optimisticUpdates.get(transaction.id);
-    if (!optimistic)
-        return Promise.resolve();
-    emitter.emit('optimistic:rollback', {
-        model: optimistic.model,
-        previousState: optimistic.previousState,
-        transaction,
-        reason: reason ?? 'unknown',
-        error,
-    });
-    optimisticUpdates.delete(transaction.id);
-    return Promise.resolve();
-}

package/dist/transactions/mutations/replayValidation.d.ts

@@ -1,187 +0,0 @@
-/**
- * The validation boundary for replaying persisted transactions after a restart.
- *
- * Rows read back from the on-disk transaction store may have been written by an
- * earlier run — possibly by an older version of this package, possibly
- * corrupted. Rather than trust them, the schemas here validate exactly the
- * fields the transaction queue and the offline-mutation restore read during
- * replay. A row that fails to parse is dropped and reported, never replayed as
- * a malformed commit.
- *
- * The same store also holds two kinds of rows that are not replayable
- * transactions — the offline mutation queue (`type: 'queue'`) and delta-await
- * markers (`type: 'awaiting_delta'`), each owned by another part of the client.
- * {@link isNonReplayablePersistedRow} recognizes them so they are skipped
- * quietly rather than flagged as corruption.
- */
-import { z } from 'zod';
-import type { QueuedMutation } from './commitPayload.js';
-import type { RuntimeContext } from '../../RuntimeContext.js';
-/**
- * The shape of a persisted transaction that can be replayed: the fields the
- * transaction queue reads when it re-enqueues the row — its id, operation type,
- * model addressing, payload, and identity context. Any remaining bookkeeping is
- * filled in with defaults when the row is rehydrated by
- * {@link deserializePersistedTransaction}.
- */
-export declare const persistedTransactionSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodEnum<{
-        update: "update";
-        create: "create";
-        delete: "delete";
-        archive: "archive";
-        unarchive: "unarchive";
-    }>;
-    modelName: z.ZodString;
-    modelId: z.ZodString;
-    modelKey: z.ZodOptional<z.ZodString>;
-    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-    context: z.ZodObject<{
-        userId: z.ZodString;
-        organizationId: z.ZodString;
-        role: z.ZodOptional<z.ZodString>;
-        teamIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>;
-    createdAt: z.ZodOptional<z.ZodNumber>;
-    batchId: z.ZodOptional<z.ZodString>;
-    commitEnvelope: z.ZodOptional<z.ZodObject<{
-        idempotencyKey: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
-        operationIndex: z.ZodNumber;
-        operationCount: z.ZodNumber;
-        sealedAt: z.ZodOptional<z.ZodNumber>;
-        sequence: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>>;
-    sourceMutationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    writeOptions: z.ZodOptional<z.ZodObject<{
-        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-            reject: "reject";
-            overwrite: "overwrite";
-            notify: "notify";
-        }>>>;
-        idempotencyKey: z.ZodOptional<z.ZodString>;
-        label: z.ZodOptional<z.ZodString>;
-        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    }, z.core.$loose>>;
-    localOnly: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$loose>;
-export type PersistedReplayableTransaction = z.infer<typeof persistedTransactionSchema>;
-/**
- * Reports whether a stored row is one of the non-transaction kinds, so callers
- * skip it instead of treating it as a corrupt transaction.
- */
-export declare function isNonReplayablePersistedRow(row: unknown): boolean;
-/**
- * Validates one stored row and rehydrates it into a {@link QueuedMutation} ready
- * to replay, or returns `null` when the row fails validation. Bookkeeping
- * fields the stored row lacks — status, attempts, priority, timestamp — are
- * re-derived the same way a freshly staged transaction derives them.
- */
-export declare function deserializePersistedTransaction(row: unknown, runtime?: RuntimeContext): QueuedMutation | null;
-/**
- * The shape of one entry in the persisted offline mutation queue — an item of
- * the `'queue'` row's `mutations` array, carrying the fields read when the
- * queue is restored on reconnect.
- */
-export declare const persistedMutationSchema: z.ZodObject<{
-    mutationId: z.ZodOptional<z.ZodString>;
-    type: z.ZodEnum<{
-        update: "update";
-        create: "create";
-        delete: "delete";
-        archive: "archive";
-    }>;
-    modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    modelName: z.ZodString;
-    timestamp: z.ZodString;
-    capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    writeOptions: z.ZodOptional<z.ZodObject<{
-        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-            reject: "reject";
-            overwrite: "overwrite";
-            notify: "notify";
-        }>>>;
-        idempotencyKey: z.ZodOptional<z.ZodString>;
-        label: z.ZodOptional<z.ZodString>;
-        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    }, z.core.$loose>>;
-}, z.core.$loose>;
-export type PersistedQueuedMutation = z.infer<typeof persistedMutationSchema>;
-export declare const PENDING_MUTATION_RECORD_PREFIX = "pending-mutation:";
-/**
- * Stay one hour inside the server's 24-hour idempotency retention window.
- * A journaled write older than this can no longer be deduplicated by the
- * server, so restore holds it for review instead of replaying it.
- */
-export declare const PENDING_MUTATION_REPLAY_WINDOW_MS: number;
-/** Scope-less records written by the first aggregate-journal release. */
-export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
-    storageVersion: z.ZodLiteral<1>;
-    id: z.ZodString;
-    type: z.ZodLiteral<"pending_mutation">;
-    mutation: z.ZodObject<{
-        type: z.ZodEnum<{
-            update: "update";
-            create: "create";
-            delete: "delete";
-            archive: "archive";
-        }>;
-        modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        modelName: z.ZodString;
-        timestamp: z.ZodString;
-        capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        writeOptions: z.ZodOptional<z.ZodObject<{
-            readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-                reject: "reject";
-                overwrite: "overwrite";
-                notify: "notify";
-            }>>>;
-            idempotencyKey: z.ZodOptional<z.ZodString>;
-            label: z.ZodOptional<z.ZodString>;
-            fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        }, z.core.$loose>>;
-        mutationId: z.ZodString;
-    }, z.core.$loose>;
-    timestamp: z.ZodNumber;
-}, z.core.$strict>;
-export declare const pendingMutationRecordSchema: z.ZodObject<{
-    storageVersion: z.ZodLiteral<2>;
-    scope: z.ZodObject<{
-        organizationId: z.ZodString;
-        participantId: z.ZodString;
-        namespace: z.ZodString;
-    }, z.core.$strict>;
-    id: z.ZodString;
-    type: z.ZodLiteral<"pending_mutation">;
-    mutation: z.ZodObject<{
-        type: z.ZodEnum<{
-            update: "update";
-            create: "create";
-            delete: "delete";
-            archive: "archive";
-        }>;
-        modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        modelName: z.ZodString;
-        timestamp: z.ZodString;
-        capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        writeOptions: z.ZodOptional<z.ZodObject<{
-            readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-                reject: "reject";
-                overwrite: "overwrite";
-                notify: "notify";
-            }>>>;
-            idempotencyKey: z.ZodOptional<z.ZodString>;
-            label: z.ZodOptional<z.ZodString>;
-            fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        }, z.core.$loose>>;
-        mutationId: z.ZodString;
-    }, z.core.$loose>;
-    timestamp: z.ZodNumber;
-}, z.core.$strict>;
-export type PendingMutationRecord = z.infer<typeof pendingMutationRecordSchema>;
-export declare function pendingMutationRecordId(mutationId: string): string;

package/dist/transactions/mutations/replayValidation.js

@@ -1,164 +0,0 @@
-/**
- * The validation boundary for replaying persisted transactions after a restart.
- *
- * Rows read back from the on-disk transaction store may have been written by an
- * earlier run — possibly by an older version of this package, possibly
- * corrupted. Rather than trust them, the schemas here validate exactly the
- * fields the transaction queue and the offline-mutation restore read during
- * replay. A row that fails to parse is dropped and reported, never replayed as
- * a malformed commit.
- *
- * The same store also holds two kinds of rows that are not replayable
- * transactions — the offline mutation queue (`type: 'queue'`) and delta-await
- * markers (`type: 'awaiting_delta'`), each owned by another part of the client.
- * {@link isNonReplayablePersistedRow} recognizes them so they are skipped
- * quietly rather than flagged as corruption.
- */
-import { z } from 'zod';
-import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
-import { globalRuntime } from '../../context.js';
-import { commitEnvelopeMemberSchema, commitOutboxScopeSchema, } from '../../transaction/transactions/settlement/commitEnvelope.js';
-import { onStaleModeSchema } from '../../transaction/coordination/schema.js';
-/** The subset of a write's options that is stored with each transaction or queued mutation. */
-const persistedWriteOptionsSchema = z
-    .object({
-    readAt: z.number().nullable().optional(),
-    onStale: onStaleModeSchema.nullable().optional(),
-    idempotencyKey: z.string().optional(),
-    label: z.string().optional(),
-    // Aligned with the `WriteOptions` type: a claimed write persisted offline
-    // must replay carrying its fencing token (Option B), or a queued write that
-    // survives a reload would lose its fence and could land as a stale blind
-    // write. Declared (not just loose-passthrough) so it is validated as a
-    // number on rehydration.
-    fenceToken: z.number().nullable().optional(),
-})
-    .loose();
-/**
- * The shape of a persisted transaction that can be replayed: the fields the
- * transaction queue reads when it re-enqueues the row — its id, operation type,
- * model addressing, payload, and identity context. Any remaining bookkeeping is
- * filled in with defaults when the row is rehydrated by
- * {@link deserializePersistedTransaction}.
- */
-export const persistedTransactionSchema = z
-    .object({
-    id: z.string().min(1),
-    type: z.enum(['create', 'update', 'delete', 'archive', 'unarchive']),
-    modelName: z.string().min(1),
-    modelId: z.string().min(1),
-    modelKey: z.string().min(1).optional(),
-    data: z.record(z.string(), z.unknown()).optional(),
-    previousData: z.record(z.string(), z.unknown()).nullable().optional(),
-    context: z.object({
-        userId: z.string().min(1),
-        organizationId: z.string().min(1),
-        role: z.string().optional(),
-        teamIds: z.array(z.string()).optional(),
-    }),
-    createdAt: z.number().optional(),
-    batchId: z.string().optional(),
-    commitEnvelope: commitEnvelopeMemberSchema.optional(),
-    sourceMutationIds: z.array(z.string().min(1)).optional(),
-    writeOptions: persistedWriteOptionsSchema.optional(),
-    localOnly: z.boolean().optional(),
-})
-    .loose();
-/** The `type` values of stored rows that belong to other parts of the client and are not replayable transactions. */
-const NON_REPLAYABLE_TYPES = new Set([
-    'queue',
-    'awaiting_delta',
-    'pending_mutation',
-    'commit_envelope',
-    'http_commit_envelope',
-]);
-/**
- * Reports whether a stored row is one of the non-transaction kinds, so callers
- * skip it instead of treating it as a corrupt transaction.
- */
-export function isNonReplayablePersistedRow(row) {
-    return (typeof row === 'object' &&
-        row !== null &&
-        typeof row.type === 'string' &&
-        NON_REPLAYABLE_TYPES.has(row.type));
-}
-/**
- * Validates one stored row and rehydrates it into a {@link QueuedMutation} ready
- * to replay, or returns `null` when the row fails validation. Bookkeeping
- * fields the stored row lacks — status, attempts, priority, timestamp — are
- * re-derived the same way a freshly staged transaction derives them.
- */
-export function deserializePersistedTransaction(row, runtime = globalRuntime) {
-    const parsed = persistedTransactionSchema.safeParse(row);
-    if (!parsed.success)
-        return null;
-    const tx = parsed.data;
-    return {
-        id: tx.id,
-        type: tx.type,
-        modelName: tx.modelName,
-        modelId: tx.modelId,
-        modelKey: tx.modelKey ?? normalizeModelKey(tx.modelName),
-        ...(tx.data !== undefined ? { data: tx.data } : {}),
-        ...(tx.previousData !== undefined ? { previousData: tx.previousData } : {}),
-        context: tx.context,
-        status: 'pending',
-        createdAt: tx.createdAt ?? Date.now(),
-        attempts: 0,
-        priority: 'normal',
-        priorityScore: computePriorityScore(tx.type, tx.modelName, runtime),
-        ...(tx.batchId !== undefined ? { batchId: tx.batchId } : {}),
-        ...(tx.commitEnvelope !== undefined
-            ? { commitEnvelope: tx.commitEnvelope }
-            : {}),
-        ...(tx.sourceMutationIds !== undefined
-            ? { sourceMutationIds: tx.sourceMutationIds }
-            : {}),
-        ...(tx.writeOptions !== undefined ? { writeOptions: tx.writeOptions } : {}),
-        ...(tx.localOnly !== undefined ? { localOnly: tx.localOnly } : {}),
-    };
-}
-/**
- * The shape of one entry in the persisted offline mutation queue — an item of
- * the `'queue'` row's `mutations` array, carrying the fields read when the
- * queue is restored on reconnect.
- */
-export const persistedMutationSchema = z
-    .object({
-    mutationId: z.string().min(1).optional(),
-    type: z.enum(['create', 'update', 'delete', 'archive']),
-    modelData: z.record(z.string(), z.unknown()),
-    modelName: z.string().min(1),
-    timestamp: z.string(),
-    capturedChanges: z.record(z.string(), z.unknown()).optional(),
-    writeOptions: persistedWriteOptionsSchema.optional(),
-})
-    .loose();
-export const PENDING_MUTATION_RECORD_PREFIX = 'pending-mutation:';
-/**
- * Stay one hour inside the server's 24-hour idempotency retention window.
- * A journaled write older than this can no longer be deduplicated by the
- * server, so restore holds it for review instead of replaying it.
- */
-export const PENDING_MUTATION_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
-const pendingMutationRecordBaseShape = {
-    id: z.string().startsWith(PENDING_MUTATION_RECORD_PREFIX),
-    type: z.literal('pending_mutation'),
-    mutation: persistedMutationSchema.extend({
-        mutationId: z.string().min(1),
-    }),
-    timestamp: z.number().int().nonnegative(),
-};
-/** Scope-less records written by the first aggregate-journal release. */
-export const legacyPendingMutationRecordSchema = z.strictObject({
-    ...pendingMutationRecordBaseShape,
-    storageVersion: z.literal(1),
-});
-export const pendingMutationRecordSchema = z.strictObject({
-    ...pendingMutationRecordBaseShape,
-    storageVersion: z.literal(2),
-    scope: commitOutboxScopeSchema,
-});
-export function pendingMutationRecordId(mutationId) {
-    return `${PENDING_MUTATION_RECORD_PREFIX}${mutationId}`;
-}

package/dist/utils/mobxSetup.d.ts

@@ -1,53 +0,0 @@
-/**
- * Wires a model instance into MobX so its schema-defined fields become
- * observable and its mutations are tracked. This module reads the property
- * metadata generated from a schema and applies the matching MobX annotation to
- * each field, leaving any hand-written getter or setter in place.
- */
-import { type AnnotationMapEntry } from 'mobx';
-import { type PropertyMetadata, type ReferenceMetadata } from '../transaction/types/index.js';
-/**
- * The subset of a model instance that {@link M1} reads and writes. A model calls
- * {@link M1} from its constructor, where these members exist on `this`;
- * declaring them here lets {@link M1} reference them without loose casts. Every
- * member is optional, so a partial model — such as a test fixture — still
- * satisfies the type.
- */
-interface M1Target {
-    _hasCustomObservability?: boolean;
-    _isConstructing?: boolean;
-    _extraMobxAnnotations?: Record<string, AnnotationMapEntry>;
-    setupObservability?(): void;
-    propertyChanged?(name: string, oldValue: unknown, newValue: unknown): void;
-}
-/**
- * Makes a model instance's schema-defined properties observable with MobX. For
- * each field it reads the {@link PropertyMetadata} and applies the matching MobX
- * annotation — a plain observable for stored values, a computed for derived
- * getters, and an action for mutating methods — while leaving any field that
- * already declares its own getter and setter untouched. If the model provides
- * its own `setupObservability` or sets `_hasCustomObservability`, this function
- * defers to it and does nothing.
- */
-export declare function M1<T extends M1Target>(target: T, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, ReferenceMetadata>): void;
-/**
- * Wraps a model class so every instance is made observable at construction time
- * by calling {@link M1}. A class that manages its own observability — one whose
- * prototype declares `setupObservability` or `_hasCustomObservability` — is
- * returned unchanged. The wrapper preserves the original class name and its
- * static members.
- */
-export declare function makeModelObservable(modelClass: any, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, any>): any;
-/**
- * Reports whether a named property is one that {@link M1} makes observable —
- * that is, a stored value, an ephemeral value, a reference collection, or a
- * reference array. Returns `false` for an unknown property and for a computed
- * reference.
- */
-export declare function isObservableProperty(target: any, propName: string, propertyMetadata: Map<string, PropertyMetadata>): boolean;
-/**
- * Returns the names of the properties that {@link M1} treats as computed: the
- * referenced-model and back-reference fields derived from a foreign key.
- */
-export declare function getComputedProperties(propertyMetadata: Map<string, PropertyMetadata>): string[];
-export {};