@abloatai/ablo 0.3.0

package/dist/testing/fixtures/bootstrap.js

@@ -0,0 +1,53 @@
+/**
+ * Bootstrap response factories for sync engine tests.
+ *
+ * Creates well-formed bootstrap responses matching the server API.
+ */
+/**
+ * Create a full bootstrap response (fresh snapshot from server).
+ */
+export function createFullBootstrapResponse(models, lastSyncId = 100) {
+    return {
+        type: 'full',
+        lastSyncId,
+        models,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Create a partial bootstrap response (delta batch from lastSyncId).
+ */
+export function createPartialBootstrapResponse(deltas, lastSyncId) {
+    return {
+        type: 'partial',
+        lastSyncId,
+        deltas,
+        deltaCount: deltas?.length ?? 0,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Create a full bootstrap response with test model data pre-populated.
+ */
+export function createTestBootstrapResponse(options = {}) {
+    const models = {};
+    if (options.tasks)
+        models.Task = options.tasks;
+    if (options.projects)
+        models.Project = options.projects;
+    if (options.slideDecks)
+        models.SlideDeck = options.slideDecks;
+    if (options.slides)
+        models.Slide = options.slides;
+    if (options.slideLayers)
+        models.SlideLayer = options.slideLayers;
+    if (options.comments)
+        models.Comment = options.comments;
+    return {
+        type: 'full',
+        lastSyncId: options.lastSyncId ?? 100,
+        models,
+        failedModels: options.failedModels,
+        timestamp: Date.now(),
+    };
+}

package/dist/testing/fixtures/deltas.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Delta factories for sync engine tests.
+ *
+ * Creates well-formed SyncAction objects matching the server wire format.
+ */
+import type { SyncActionType, SyncAction } from '../../types/index.js';
+/** Reset the delta counter (call in beforeEach for deterministic IDs) */
+export declare function resetDeltaCounter(): void;
+export interface CreateDeltaOptions {
+    /** Sync ID (auto-increments if not provided) */
+    id?: number;
+    /** Model name (e.g., 'Task', 'Slide') */
+    modelName: string;
+    /** Model ID */
+    modelId: string;
+    /** Action type: I=Insert, U=Update, D=Delete, A=Archive, V=Unarchive */
+    action: SyncActionType;
+    /** Delta payload data */
+    data?: Record<string, unknown>;
+}
+/**
+ * Create a single SyncAction (delta) matching the server wire format.
+ */
+export declare function createDelta(options: CreateDeltaOptions): SyncAction;
+/**
+ * Create an INSERT delta for a new entity.
+ */
+export declare function createInsertDelta(modelName: string, modelId: string, data: Record<string, unknown>, syncId?: number): SyncAction;
+/**
+ * Create an UPDATE delta for an existing entity.
+ */
+export declare function createUpdateDelta(modelName: string, modelId: string, data: Record<string, unknown>, syncId?: number): SyncAction;
+/**
+ * Create a DELETE delta.
+ */
+export declare function createDeleteDelta(modelName: string, modelId: string, syncId?: number): SyncAction;
+/**
+ * Create an ARCHIVE delta.
+ */
+export declare function createArchiveDelta(modelName: string, modelId: string, syncId?: number): SyncAction;
+/**
+ * Create an UNARCHIVE (reVive) delta.
+ */
+export declare function createUnarchiveDelta(modelName: string, modelId: string, syncId?: number): SyncAction;
+/**
+ * Create a COVERING ('C') delta.
+ *
+ * Signals that the client has gained permission to see an existing entity.
+ * Treated as an insert by the client — the entity is added to the local
+ * store as if newly created. Typically follows a GroupAdded delta.
+ */
+export declare function createCoveringDelta(modelName: string, modelId: string, data: Record<string, unknown>, syncId?: number): SyncAction;
+/**
+ * Create a GROUP ADDED ('G') delta using the incremental payload shape.
+ *
+ * Signals that the recipient was added to a single sync group. The client
+ * updates its subscription metadata and waits for Covering deltas to
+ * deliver the newly-visible entities. Unlike the legacy 'G' payload
+ * (addedGroups/removedGroups), this does not trigger a re-bootstrap.
+ */
+export declare function createGroupAddedDelta(userId: string, group: string, syncId?: number): SyncAction;
+/**
+ * Create a legacy GROUP CHANGE ('G') delta with the old payload shape.
+ *
+ * Carries both added and removed groups in one delta and forces a full
+ * re-bootstrap on the client. Use for testing backward compatibility with
+ * the deprecated EmitGroupChange path.
+ */
+export declare function createLegacyGroupChangeDelta(userId: string, added: string[], removed: string[], syncId?: number): SyncAction;
+/**
+ * Create a GROUP REMOVED ('S') delta.
+ *
+ * Signals that the recipient lost access to a sync group. The client
+ * purges affected local state and triggers a re-bootstrap with the
+ * updated group list.
+ */
+export declare function createGroupRemovedDelta(userId: string, group: string, syncId?: number): SyncAction;
+/**
+ * Create a batch of deltas with sequential sync IDs.
+ */
+export declare function createDeltaBatch(deltas: Array<Omit<CreateDeltaOptions, 'id'>>, startingSyncId?: number): SyncAction[];
+/**
+ * Create a confirmation delta — used to confirm that a mutation
+ * was persisted by the server (TransactionQueue watches for this).
+ */
+export declare function createConfirmationDelta(modelName: string, modelId: string, syncId: number, action?: SyncActionType, data?: Record<string, unknown>): SyncAction;

package/dist/testing/fixtures/deltas.js

@@ -0,0 +1,139 @@
+/**
+ * Delta factories for sync engine tests.
+ *
+ * Creates well-formed SyncAction objects matching the server wire format.
+ */
+let deltaCounter = 0;
+/** Reset the delta counter (call in beforeEach for deterministic IDs) */
+export function resetDeltaCounter() {
+    deltaCounter = 0;
+}
+/**
+ * Create a single SyncAction (delta) matching the server wire format.
+ */
+export function createDelta(options) {
+    deltaCounter++;
+    return {
+        id: options.id ?? deltaCounter,
+        modelName: options.modelName,
+        modelId: options.modelId,
+        action: options.action,
+        data: options.data ?? {},
+        __class: 'SyncAction',
+    };
+}
+/**
+ * Create an INSERT delta for a new entity.
+ */
+export function createInsertDelta(modelName, modelId, data, syncId) {
+    return createDelta({ modelName, modelId, action: 'I', data, id: syncId });
+}
+/**
+ * Create an UPDATE delta for an existing entity.
+ */
+export function createUpdateDelta(modelName, modelId, data, syncId) {
+    return createDelta({ modelName, modelId, action: 'U', data, id: syncId });
+}
+/**
+ * Create a DELETE delta.
+ */
+export function createDeleteDelta(modelName, modelId, syncId) {
+    return createDelta({ modelName, modelId, action: 'D', data: {}, id: syncId });
+}
+/**
+ * Create an ARCHIVE delta.
+ */
+export function createArchiveDelta(modelName, modelId, syncId) {
+    return createDelta({
+        modelName,
+        modelId,
+        action: 'A',
+        data: { archivedAt: new Date().toISOString() },
+        id: syncId,
+    });
+}
+/**
+ * Create an UNARCHIVE (reVive) delta.
+ */
+export function createUnarchiveDelta(modelName, modelId, syncId) {
+    return createDelta({
+        modelName,
+        modelId,
+        action: 'V',
+        data: { archivedAt: null },
+        id: syncId,
+    });
+}
+/**
+ * Create a COVERING ('C') delta.
+ *
+ * Signals that the client has gained permission to see an existing entity.
+ * Treated as an insert by the client — the entity is added to the local
+ * store as if newly created. Typically follows a GroupAdded delta.
+ */
+export function createCoveringDelta(modelName, modelId, data, syncId) {
+    return createDelta({ modelName, modelId, action: 'C', data, id: syncId });
+}
+/**
+ * Create a GROUP ADDED ('G') delta using the incremental payload shape.
+ *
+ * Signals that the recipient was added to a single sync group. The client
+ * updates its subscription metadata and waits for Covering deltas to
+ * deliver the newly-visible entities. Unlike the legacy 'G' payload
+ * (addedGroups/removedGroups), this does not trigger a re-bootstrap.
+ */
+export function createGroupAddedDelta(userId, group, syncId) {
+    return createDelta({
+        modelName: 'SyncGroupChange',
+        modelId: `sga_${userId}`,
+        action: 'G',
+        data: { group, userId },
+        id: syncId,
+    });
+}
+/**
+ * Create a legacy GROUP CHANGE ('G') delta with the old payload shape.
+ *
+ * Carries both added and removed groups in one delta and forces a full
+ * re-bootstrap on the client. Use for testing backward compatibility with
+ * the deprecated EmitGroupChange path.
+ */
+export function createLegacyGroupChangeDelta(userId, added, removed, syncId) {
+    return createDelta({
+        modelName: 'SyncGroupChange',
+        modelId: `sgc_${userId}`,
+        action: 'G',
+        data: { addedGroups: added, removedGroups: removed },
+        id: syncId,
+    });
+}
+/**
+ * Create a GROUP REMOVED ('S') delta.
+ *
+ * Signals that the recipient lost access to a sync group. The client
+ * purges affected local state and triggers a re-bootstrap with the
+ * updated group list.
+ */
+export function createGroupRemovedDelta(userId, group, syncId) {
+    return createDelta({
+        modelName: 'SyncGroupChange',
+        modelId: `sgr_${userId}`,
+        action: 'S',
+        data: { group, userId },
+        id: syncId,
+    });
+}
+/**
+ * Create a batch of deltas with sequential sync IDs.
+ */
+export function createDeltaBatch(deltas, startingSyncId) {
+    const start = startingSyncId ?? deltaCounter + 1;
+    return deltas.map((d, i) => createDelta({ ...d, id: start + i }));
+}
+/**
+ * Create a confirmation delta — used to confirm that a mutation
+ * was persisted by the server (TransactionQueue watches for this).
+ */
+export function createConfirmationDelta(modelName, modelId, syncId, action = 'U', data = {}) {
+    return createDelta({ modelName, modelId, action, data, id: syncId });
+}

package/dist/testing/fixtures/models.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Test Model subclasses for @ablo/sync-engine tests.
+ *
+ * Lightweight Model implementations with FK relationships matching
+ * the MODEL_CREATE_PRIORITY map in TransactionQueue:
+ *   TestProject (10) → TestTask (10, FK→Project) → TestComment (30, FK→Task)
+ *   TestSlideDeck (10) → TestSlide (15, FK→SlideDeck) → TestSlideLayer (20, FK→Slide)
+ */
+import { Model } from '../../Model.js';
+import { ModelRegistry } from '../../ModelRegistry.js';
+export declare class TestProject extends Model {
+    name: string;
+    description: string;
+    organizationId: string;
+    constructor(data?: Partial<TestProject> & Record<string, unknown>);
+    getModelName(): string;
+}
+export declare class TestTask extends Model {
+    title: string;
+    status: string;
+    projectId: string | null;
+    assigneeId: string | null;
+    organizationId: string;
+    constructor(data?: Partial<TestTask> & Record<string, unknown>);
+    getModelName(): string;
+}
+export declare class TestComment extends Model {
+    body: string;
+    taskId: string | null;
+    organizationId: string;
+    constructor(data?: Partial<TestComment> & Record<string, unknown>);
+    getModelName(): string;
+}
+export declare class TestSlideDeck extends Model {
+    title: string;
+    organizationId: string;
+    constructor(data?: Partial<TestSlideDeck> & Record<string, unknown>);
+    getModelName(): string;
+}
+export declare class TestSlide extends Model {
+    order: number;
+    deckId: string | null;
+    organizationId: string;
+    constructor(data?: Partial<TestSlide> & Record<string, unknown>);
+    getModelName(): string;
+}
+export declare class TestSlideLayer extends Model {
+    slideId: string | null;
+    zIndex: number;
+    type: string;
+    content: string;
+    organizationId: string;
+    constructor(data?: Partial<TestSlideLayer> & Record<string, unknown>);
+    getModelName(): string;
+}
+/**
+ * Model → priority mapping matching TransactionQueue's MODEL_CREATE_PRIORITY.
+ */
+export declare const TEST_MODEL_PRIORITIES: Map<string, number>;
+/**
+ * Register all test models with a ModelRegistry instance.
+ * Sets up properties, references, and FK relationships.
+ */
+export declare function registerTestModels(registry: ModelRegistry): void;
+/**
+ * Create a SyncEngineConfig pre-configured with test model priorities.
+ */
+export declare function createTestConfig(): {
+    modelCreatePriority: ReadonlyMap<string, number>;
+    defaultCreatePriority: number;
+    defaultNonCreatePriority: number;
+    essentialFields: Readonly<Record<string, readonly string[]>>;
+    classNameFallbackMap: Readonly<Record<string, string>>;
+};
+/** Reset the counter (call in beforeEach for deterministic IDs) */
+export declare function resetFixtureCounter(): void;
+export declare function createProjectFixture(overrides?: Partial<Record<string, unknown>>): TestProject;
+export declare function createTaskFixture(overrides?: Partial<Record<string, unknown>>): TestTask;
+export declare function createCommentFixture(overrides?: Partial<Record<string, unknown>>): TestComment;
+export declare function createSlideDeckFixture(overrides?: Partial<Record<string, unknown>>): TestSlideDeck;
+export declare function createSlideFixture(overrides?: Partial<Record<string, unknown>>): TestSlide;
+export declare function createSlideLayerFixture(overrides?: Partial<Record<string, unknown>>): TestSlideLayer;

package/dist/testing/fixtures/models.js

@@ -0,0 +1,270 @@
+/**
+ * Test Model subclasses for @ablo/sync-engine tests.
+ *
+ * Lightweight Model implementations with FK relationships matching
+ * the MODEL_CREATE_PRIORITY map in TransactionQueue:
+ *   TestProject (10) → TestTask (10, FK→Project) → TestComment (30, FK→Task)
+ *   TestSlideDeck (10) → TestSlide (15, FK→SlideDeck) → TestSlideLayer (20, FK→Slide)
+ */
+import { Model } from '../../Model.js';
+import { PropertyType, LoadStrategy } from '../../types/index.js';
+// ─────────────────────────────────────────────
+// Test Model Classes
+// ─────────────────────────────────────────────
+export class TestProject extends Model {
+    name = '';
+    description = '';
+    organizationId = 'test-org';
+    constructor(data = {}) {
+        super(data);
+        if (data.name != null)
+            this.name = data.name;
+        if (data.description != null)
+            this.description = data.description;
+        if (data.organizationId != null)
+            this.organizationId = data.organizationId;
+    }
+    getModelName() {
+        return 'Project';
+    }
+}
+export class TestTask extends Model {
+    title = '';
+    status = 'todo';
+    projectId = null;
+    assigneeId = null;
+    organizationId = 'test-org';
+    constructor(data = {}) {
+        super(data);
+        if (data.title != null)
+            this.title = data.title;
+        if (data.status != null)
+            this.status = data.status;
+        if (data.projectId !== undefined)
+            this.projectId = data.projectId;
+        if (data.assigneeId !== undefined)
+            this.assigneeId = data.assigneeId;
+        if (data.organizationId != null)
+            this.organizationId = data.organizationId;
+    }
+    getModelName() {
+        return 'Task';
+    }
+}
+export class TestComment extends Model {
+    body = '';
+    taskId = null;
+    organizationId = 'test-org';
+    constructor(data = {}) {
+        super(data);
+        if (data.body != null)
+            this.body = data.body;
+        if (data.taskId !== undefined)
+            this.taskId = data.taskId;
+        if (data.organizationId != null)
+            this.organizationId = data.organizationId;
+    }
+    getModelName() {
+        return 'Comment';
+    }
+}
+export class TestSlideDeck extends Model {
+    title = '';
+    organizationId = 'test-org';
+    constructor(data = {}) {
+        super(data);
+        if (data.title != null)
+            this.title = data.title;
+        if (data.organizationId != null)
+            this.organizationId = data.organizationId;
+    }
+    getModelName() {
+        return 'SlideDeck';
+    }
+}
+export class TestSlide extends Model {
+    order = 0;
+    deckId = null;
+    organizationId = 'test-org';
+    constructor(data = {}) {
+        super(data);
+        if (data.order != null)
+            this.order = data.order;
+        if (data.deckId !== undefined)
+            this.deckId = data.deckId;
+        if (data.organizationId != null)
+            this.organizationId = data.organizationId;
+    }
+    getModelName() {
+        return 'Slide';
+    }
+}
+export class TestSlideLayer extends Model {
+    slideId = null;
+    zIndex = 0;
+    type = 'text';
+    content = '';
+    organizationId = 'test-org';
+    constructor(data = {}) {
+        super(data);
+        if (data.slideId !== undefined)
+            this.slideId = data.slideId;
+        if (data.zIndex != null)
+            this.zIndex = data.zIndex;
+        if (data.type != null)
+            this.type = data.type;
+        if (data.content != null)
+            this.content = data.content;
+        if (data.organizationId != null)
+            this.organizationId = data.organizationId;
+    }
+    getModelName() {
+        return 'SlideLayer';
+    }
+}
+// ─────────────────────────────────────────────
+// Model Registration Helper
+// ─────────────────────────────────────────────
+/**
+ * Model → priority mapping matching TransactionQueue's MODEL_CREATE_PRIORITY.
+ */
+export const TEST_MODEL_PRIORITIES = new Map([
+    ['Project', 10],
+    ['Task', 10],
+    ['SlideDeck', 10],
+    ['Slide', 15],
+    ['SlideLayer', 20],
+    ['Comment', 30],
+]);
+/**
+ * Register all test models with a ModelRegistry instance.
+ * Sets up properties, references, and FK relationships.
+ */
+export function registerTestModels(registry) {
+    registry.startBatch();
+    // Register model classes
+    registry.registerModel('Project', TestProject, { loadStrategy: LoadStrategy.instant });
+    registry.registerModel('Task', TestTask, { loadStrategy: LoadStrategy.instant });
+    registry.registerModel('Comment', TestComment, { loadStrategy: LoadStrategy.instant });
+    registry.registerModel('SlideDeck', TestSlideDeck, { loadStrategy: LoadStrategy.instant });
+    registry.registerModel('Slide', TestSlide, { loadStrategy: LoadStrategy.instant });
+    registry.registerModel('SlideLayer', TestSlideLayer, { loadStrategy: LoadStrategy.instant });
+    // Register properties
+    registry.registerProperty('Project', 'name', { type: PropertyType.property });
+    registry.registerProperty('Project', 'description', { type: PropertyType.property, optional: true });
+    registry.registerProperty('Project', 'organizationId', { type: PropertyType.property });
+    registry.registerProperty('Task', 'title', { type: PropertyType.property });
+    registry.registerProperty('Task', 'status', { type: PropertyType.property });
+    registry.registerProperty('Task', 'projectId', { type: PropertyType.reference, nullable: true });
+    registry.registerProperty('Task', 'assigneeId', { type: PropertyType.reference, nullable: true });
+    registry.registerProperty('Task', 'organizationId', { type: PropertyType.property });
+    registry.registerProperty('Comment', 'body', { type: PropertyType.property });
+    registry.registerProperty('Comment', 'taskId', { type: PropertyType.reference, nullable: true });
+    registry.registerProperty('Comment', 'organizationId', { type: PropertyType.property });
+    registry.registerProperty('SlideDeck', 'title', { type: PropertyType.property });
+    registry.registerProperty('SlideDeck', 'organizationId', { type: PropertyType.property });
+    registry.registerProperty('Slide', 'order', { type: PropertyType.property });
+    registry.registerProperty('Slide', 'deckId', { type: PropertyType.reference, nullable: true });
+    registry.registerProperty('Slide', 'organizationId', { type: PropertyType.property });
+    registry.registerProperty('SlideLayer', 'slideId', { type: PropertyType.reference, nullable: true });
+    registry.registerProperty('SlideLayer', 'zIndex', { type: PropertyType.property });
+    registry.registerProperty('SlideLayer', 'type', { type: PropertyType.property });
+    registry.registerProperty('SlideLayer', 'content', { type: PropertyType.property });
+    registry.registerProperty('SlideLayer', 'organizationId', { type: PropertyType.property });
+    // Register back-references for cascade-aware transaction handling
+    registry.registerBackReference('Task', { parentModel: 'Project', foreignKey: 'projectId', cascadeDelete: true });
+    registry.registerBackReference('Comment', { parentModel: 'Task', foreignKey: 'taskId', cascadeDelete: true });
+    registry.registerBackReference('Slide', { parentModel: 'SlideDeck', foreignKey: 'deckId', cascadeDelete: true });
+    registry.registerBackReference('SlideLayer', { parentModel: 'Slide', foreignKey: 'slideId', cascadeDelete: true });
+    registry.endBatch();
+}
+// ─────────────────────────────────────────────
+// Test SyncEngineConfig factory
+// ─────────────────────────────────────────────
+/**
+ * Create a SyncEngineConfig pre-configured with test model priorities.
+ */
+export function createTestConfig() {
+    return {
+        modelCreatePriority: TEST_MODEL_PRIORITIES,
+        defaultCreatePriority: 40,
+        defaultNonCreatePriority: 50,
+        essentialFields: {
+            Task: ['title', 'projectId'],
+            Slide: ['deckId', 'order'],
+        },
+        classNameFallbackMap: {
+            TestProject: 'Project',
+            TestTask: 'Task',
+            TestComment: 'Comment',
+            TestSlideDeck: 'SlideDeck',
+            TestSlide: 'Slide',
+            TestSlideLayer: 'SlideLayer',
+        },
+    };
+}
+// ─────────────────────────────────────────────
+// Fixture factories
+// ─────────────────────────────────────────────
+let fixtureCounter = 0;
+/** Reset the counter (call in beforeEach for deterministic IDs) */
+export function resetFixtureCounter() {
+    fixtureCounter = 0;
+}
+export function createProjectFixture(overrides = {}) {
+    fixtureCounter++;
+    return new TestProject({
+        id: `project-${fixtureCounter}`,
+        name: `Test Project ${fixtureCounter}`,
+        organizationId: 'test-org',
+        ...overrides,
+    });
+}
+export function createTaskFixture(overrides = {}) {
+    fixtureCounter++;
+    return new TestTask({
+        id: `task-${fixtureCounter}`,
+        title: `Test Task ${fixtureCounter}`,
+        status: 'todo',
+        organizationId: 'test-org',
+        ...overrides,
+    });
+}
+export function createCommentFixture(overrides = {}) {
+    fixtureCounter++;
+    return new TestComment({
+        id: `comment-${fixtureCounter}`,
+        body: `Test comment ${fixtureCounter}`,
+        organizationId: 'test-org',
+        ...overrides,
+    });
+}
+export function createSlideDeckFixture(overrides = {}) {
+    fixtureCounter++;
+    return new TestSlideDeck({
+        id: `deck-${fixtureCounter}`,
+        title: `Test Deck ${fixtureCounter}`,
+        organizationId: 'test-org',
+        ...overrides,
+    });
+}
+export function createSlideFixture(overrides = {}) {
+    fixtureCounter++;
+    return new TestSlide({
+        id: `slide-${fixtureCounter}`,
+        order: fixtureCounter,
+        organizationId: 'test-org',
+        ...overrides,
+    });
+}
+export function createSlideLayerFixture(overrides = {}) {
+    fixtureCounter++;
+    return new TestSlideLayer({
+        id: `layer-${fixtureCounter}`,
+        zIndex: fixtureCounter,
+        type: 'text',
+        content: `Layer content ${fixtureCounter}`,
+        organizationId: 'test-org',
+        ...overrides,
+    });
+}