@aelionsdk/transaction 0.1.0-beta.1

package/dist/transaction.js

@@ -0,0 +1,222 @@
+import { AelionError } from '@aelionsdk/core';
+import { canonicalClone, } from '@aelionsdk/project-schema';
+import { collectAffectedRanges } from './affected-ranges.js';
+import { applyOperations } from './operations.js';
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        Object.values(value).forEach(entry => deepFreeze(entry));
+    }
+    return value;
+}
+function transactionError(code, message) {
+    return new AelionError([
+        {
+            code,
+            severity: 'error',
+            message,
+            recoverable: true,
+        },
+    ]);
+}
+function createDraft(project, operations) {
+    const draft = { ...project };
+    const collections = new Set(operations.map(operation => operation.collection));
+    for (const collection of collections) {
+        const source = project[collection];
+        const cloned = { ...source };
+        const entityIds = new Set(operations
+            .filter(operation => operation.collection === collection)
+            .map(operation => operation.id));
+        for (const id of entityIds) {
+            const entity = source[id];
+            if (entity !== undefined)
+                cloned[id] = canonicalClone(entity);
+        }
+        Reflect.set(draft, collection, cloned);
+    }
+    return draft;
+}
+let changeSetSequence = 0;
+export const TRANSACTION_MAX_OPERATIONS = 16_384;
+function createChangeSetId() {
+    changeSetSequence += 1;
+    return `chg_${Date.now().toString(36)}_${changeSetSequence.toString(36)}`;
+}
+export class TransactionBuilder {
+    #operations = [];
+    get operations() {
+        return this.#operations;
+    }
+    /**
+     * Appends an already validated operation sequence to this transaction.
+     *
+     * This is primarily used by history/replay adapters. Operations are cloned so
+     * callers cannot mutate a transaction after it has been committed.
+     */
+    appendOperations(operations) {
+        if (this.#operations.length + operations.length > TRANSACTION_MAX_OPERATIONS) {
+            throw transactionError('TRANSACTION_OPERATION_LIMIT_EXCEEDED', `A transaction cannot contain more than ${TRANSACTION_MAX_OPERATIONS.toString()} operations`);
+        }
+        this.#operations.push(...operations.map(operation => structuredClone(operation)));
+    }
+    createEntity(collection, id, value) {
+        this.#push({ op: 'createEntity', collection, id, value });
+    }
+    deleteEntity(collection, id) {
+        this.#push({ op: 'deleteEntity', collection, id });
+    }
+    setField(collection, id, path, value) {
+        this.#push({ op: 'setField', collection, id, path, value });
+    }
+    removeField(collection, id, path) {
+        this.#push({ op: 'removeField', collection, id, path });
+    }
+    listInsert(collection, id, path, valueId, beforeId) {
+        this.#push({
+            op: 'listInsert',
+            collection,
+            id,
+            path,
+            valueId,
+            ...(beforeId === undefined ? {} : { beforeId }),
+        });
+    }
+    listRemove(collection, id, path, valueId) {
+        this.#push({ op: 'listRemove', collection, id, path, valueId });
+    }
+    listMove(collection, id, path, valueId, beforeId) {
+        this.#push({
+            op: 'listMove',
+            collection,
+            id,
+            path,
+            valueId,
+            ...(beforeId === undefined ? {} : { beforeId }),
+        });
+    }
+    #push(operation) {
+        if (this.#operations.length >= TRANSACTION_MAX_OPERATIONS) {
+            throw transactionError('TRANSACTION_OPERATION_LIMIT_EXCEEDED', `A transaction cannot contain more than ${TRANSACTION_MAX_OPERATIONS.toString()} operations`);
+        }
+        this.#operations.push(operation);
+    }
+}
+export class TransactionEngine {
+    #validate;
+    #prepareCommit;
+    #listeners = new Set();
+    #project;
+    #revision = 0n;
+    #committing = false;
+    #reentrantAttempted = false;
+    constructor(project, validate, options = {}) {
+        const cloned = canonicalClone(project);
+        const result = validate(cloned);
+        if (!result.ok)
+            throw new AelionError(result.diagnostics);
+        this.#project = deepFreeze(cloned);
+        this.#validate = validate;
+        this.#prepareCommit = options.prepareCommit;
+    }
+    get revision() {
+        return this.#revision;
+    }
+    getSnapshot() {
+        return this.#project;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    edit(options, callback) {
+        if (this.#committing) {
+            this.#reentrantAttempted = true;
+            throw transactionError('TRANSACTION_REENTRANT', 'A transaction cannot start while another transaction is being committed');
+        }
+        this.#committing = true;
+        this.#reentrantAttempted = false;
+        try {
+            const baseRevision = options.baseRevision ?? this.#revision;
+            if (baseRevision !== this.#revision) {
+                throw transactionError('REVISION_CONFLICT', `Expected revision ${baseRevision}, current revision is ${this.#revision}`);
+            }
+            const before = this.#project;
+            const transaction = new TransactionBuilder();
+            callback(transaction);
+            this.#assertNoReentrantAttempt();
+            if (transaction.operations.length === 0) {
+                throw transactionError('TRANSACTION_EMPTY', 'A transaction must contain an operation');
+            }
+            const draft = createDraft(before, transaction.operations);
+            const inverse = applyOperations(draft, transaction.operations);
+            const validation = this.#validate(draft);
+            if (!validation.ok)
+                throw new AelionError(validation.diagnostics);
+            this.#assertNoReentrantAttempt();
+            this.#assertBaseUnchanged(baseRevision, before);
+            const committedRevision = baseRevision + 1n;
+            const affectedEntityIds = [
+                ...new Set(transaction.operations.map(operation => operation.id)),
+            ].sort();
+            const changeSet = {
+                id: createChangeSetId(),
+                baseRevision,
+                committedRevision,
+                ...(options.label === undefined ? {} : { label: options.label }),
+                operations: transaction.operations.map(operation => structuredClone(operation)),
+                affectedEntityIds,
+                affectedRanges: collectAffectedRanges(before, draft, transaction.operations),
+            };
+            const snapshot = deepFreeze(draft);
+            const commit = {
+                revision: committedRevision,
+                snapshot,
+                changeSet,
+                inverse,
+            };
+            const prepared = this.#prepareCommit?.(commit);
+            this.#assertNoReentrantAttempt();
+            this.#assertBaseUnchanged(baseRevision, before);
+            prepared?.publish();
+            this.#assertNoReentrantAttempt();
+            this.#assertBaseUnchanged(baseRevision, before);
+            this.#project = snapshot;
+            this.#revision = committedRevision;
+            // Change listeners are post-commit observers. One observer must not make
+            // a successful commit appear to fail or extend this dispatch by adding
+            // listeners while it is in progress.
+            for (const listener of [...this.#listeners]) {
+                try {
+                    listener(commit);
+                }
+                catch {
+                    // Observer failures do not roll back an already-published commit.
+                }
+            }
+            return commit;
+        }
+        finally {
+            this.#committing = false;
+            this.#reentrantAttempted = false;
+        }
+    }
+    applyChangeSet(changeSet) {
+        return this.edit({
+            ...(changeSet.label === undefined ? {} : { label: changeSet.label }),
+            baseRevision: changeSet.baseRevision,
+        }, transaction => {
+            transaction.appendOperations(changeSet.operations);
+        });
+    }
+    #assertBaseUnchanged(baseRevision, before) {
+        if (this.#revision === baseRevision && this.#project === before)
+            return;
+        throw transactionError('REVISION_CONFLICT', `Expected revision ${baseRevision}, current revision is ${this.#revision}`);
+    }
+    #assertNoReentrantAttempt() {
+        if (!this.#reentrantAttempted)
+            return;
+        throw transactionError('TRANSACTION_REENTRANT', 'A nested transaction was attempted while this transaction was being committed');
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+import type { Diagnostic, JsonObject, JsonValue } from '@aelionsdk/core';
+import type { AelionProject, CollectionName, EntityId, TimeRange } from '@aelionsdk/project-schema';
+export type AtomicOperation = {
+    readonly op: 'createEntity';
+    readonly collection: CollectionName;
+    readonly id: EntityId;
+    readonly value: JsonObject;
+} | {
+    readonly op: 'deleteEntity';
+    readonly collection: CollectionName;
+    readonly id: EntityId;
+} | {
+    readonly op: 'setField';
+    readonly collection: CollectionName;
+    readonly id: EntityId;
+    readonly path: readonly string[];
+    readonly value: JsonValue;
+} | {
+    readonly op: 'removeField';
+    readonly collection: CollectionName;
+    readonly id: EntityId;
+    readonly path: readonly string[];
+} | {
+    readonly op: 'listInsert';
+    readonly collection: CollectionName;
+    readonly id: EntityId;
+    readonly path: readonly string[];
+    readonly beforeId?: EntityId;
+    readonly valueId: EntityId;
+} | {
+    readonly op: 'listRemove';
+    readonly collection: CollectionName;
+    readonly id: EntityId;
+    readonly path: readonly string[];
+    readonly valueId: EntityId;
+} | {
+    readonly op: 'listMove';
+    readonly collection: CollectionName;
+    readonly id: EntityId;
+    readonly path: readonly string[];
+    readonly beforeId?: EntityId;
+    readonly valueId: EntityId;
+};
+export interface AffectedRange extends TimeRange {
+    readonly sequenceId: EntityId;
+}
+export interface ChangeSet {
+    readonly id: string;
+    readonly baseRevision: bigint;
+    readonly committedRevision: bigint;
+    readonly label?: string;
+    readonly operations: readonly AtomicOperation[];
+    readonly affectedEntityIds: readonly EntityId[];
+    readonly affectedRanges: readonly AffectedRange[];
+}
+export interface TransactionCommit {
+    readonly revision: bigint;
+    readonly snapshot: Readonly<AelionProject>;
+    readonly changeSet: ChangeSet;
+    readonly inverse: readonly AtomicOperation[];
+}
+export interface EditOptions {
+    readonly label?: string;
+    readonly baseRevision?: bigint;
+    /** Consecutive edits with the same key are stored as one undo/redo entry. */
+    readonly historyGroup?: string;
+}
+export interface TransactionValidationResult {
+    readonly ok: boolean;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type ProjectValidation = (project: unknown) => TransactionValidationResult;
+export type ProjectChangeListener = (commit: TransactionCommit) => void;
+/**
+ * A prepared, synchronous side effect that is published immediately before the
+ * Project snapshot and revision become visible. Implementations must not call
+ * consumer code; throwing prevents the TransactionEngine commit.
+ */
+export interface PreparedTransactionCommit {
+    publish(): void;
+}
+/**
+ * Prepares derived state for a candidate commit without mutating the active
+ * Project. This is used by hosts such as AelionSession to compile Render IR as
+ * part of the same atomic commit boundary.
+ */
+export type TransactionCommitPreparer = (commit: TransactionCommit) => PreparedTransactionCommit | undefined;
+export interface TransactionEngineOptions {
+    readonly prepareCommit?: TransactionCommitPreparer;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@aelionsdk/transaction",
+  "version": "0.1.0-beta.1",
+  "description": "Atomic project transactions, inverses and change sets for AelionSDK",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FoyonaCZY/AelionSDK.git",
+    "directory": "packages/transaction"
+  },
+  "keywords": [
+    "aelion",
+    "timeline",
+    "transaction",
+    "undo"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@aelionsdk/core": "0.1.0-beta.1",
+    "@aelionsdk/project-schema": "0.1.0-beta.1"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty false"
+  }
+}