@continuum-dev/session 0.1.0

package/lib/session/view-pusher.d.ts

@@ -0,0 +1,13 @@
+import type { ViewDefinition } from '@continuum/contract';
+import type { SessionState } from './session-state.js';
+/**
+ * Pushes a new view definition into the session and reconciles existing data.
+ *
+ * Updates reconciliation artifacts, marks stale pending intents when view version
+ * changes, creates an auto checkpoint, runs detached-value GC, and notifies listeners.
+ *
+ * @param internal Mutable internal session state.
+ * @param view Next view definition to apply.
+ */
+export declare function pushView(internal: SessionState, view: ViewDefinition): void;
+//# sourceMappingURL=view-pusher.d.ts.map

package/lib/session/view-pusher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-pusher.d.ts","sourceRoot":"","sources":["../../../../../packages/session/src/lib/session/view-pusher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA+EvD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAiC3E"}

package/lib/session/view-pusher.js

@@ -0,0 +1,104 @@
+import { reconcile } from '@continuum/runtime';
+import { autoCheckpoint } from './checkpoint-manager.js';
+import { markAllPendingIntentsAsStale } from './intent-manager.js';
+import { notifySnapshotAndIssueListeners } from './listeners.js';
+function assertValidView(view) {
+    if (typeof view.viewId !== 'string' || view.viewId.length === 0) {
+        throw new Error('Invalid view: "viewId" must be a non-empty string');
+    }
+    if (typeof view.version !== 'string' || view.version.length === 0) {
+        throw new Error('Invalid view: "version" must be a non-empty string');
+    }
+    if (!Array.isArray(view.nodes)) {
+        throw new Error('Invalid view: "nodes" must be an array');
+    }
+}
+function runDetachedValueGC(internal) {
+    const policy = internal.detachedValuePolicy;
+    const detached = internal.currentData?.detachedValues;
+    if (!policy || !detached || Object.keys(detached).length === 0) {
+        return;
+    }
+    const now = internal.clock();
+    const entries = Object.entries(detached);
+    const toRemove = new Set();
+    // Increment pushesSinceDetach for all entries
+    for (const [, value] of entries) {
+        value.pushesSinceDetach = (value.pushesSinceDetach ?? 0) + 1;
+    }
+    // Strategy: maxAge
+    if (policy.maxAge !== undefined) {
+        for (const [key, value] of entries) {
+            if (now - value.detachedAt > policy.maxAge) {
+                toRemove.add(key);
+            }
+        }
+    }
+    // Strategy: pushCount
+    if (policy.pushCount !== undefined) {
+        for (const [key, value] of entries) {
+            if ((value.pushesSinceDetach ?? 0) >= policy.pushCount) {
+                toRemove.add(key);
+            }
+        }
+    }
+    // Strategy: maxCount (FIFO — oldest first)
+    if (policy.maxCount !== undefined) {
+        const remaining = entries
+            .filter(([key]) => !toRemove.has(key))
+            .sort(([, a], [, b]) => a.detachedAt - b.detachedAt);
+        while (remaining.length > policy.maxCount) {
+            const oldest = remaining.shift();
+            toRemove.add(oldest[0]);
+        }
+    }
+    if (toRemove.size === 0)
+        return;
+    const updated = {};
+    for (const [key, value] of entries) {
+        if (!toRemove.has(key)) {
+            updated[key] = value;
+        }
+    }
+    if (Object.keys(updated).length === 0) {
+        const { detachedValues: _, ...rest } = internal.currentData;
+        internal.currentData = rest;
+    }
+    else {
+        internal.currentData = { ...internal.currentData, detachedValues: updated };
+    }
+}
+/**
+ * Pushes a new view definition into the session and reconciles existing data.
+ *
+ * Updates reconciliation artifacts, marks stale pending intents when view version
+ * changes, creates an auto checkpoint, runs detached-value GC, and notifies listeners.
+ *
+ * @param internal Mutable internal session state.
+ * @param view Next view definition to apply.
+ */
+export function pushView(internal, view) {
+    if (internal.destroyed)
+        return;
+    assertValidView(view);
+    const priorVersion = internal.currentView?.version;
+    internal.priorView = internal.currentView;
+    internal.currentView = view;
+    const result = reconcile(view, internal.priorView, internal.currentData, { clock: internal.clock, ...(internal.reconciliationOptions ?? {}) });
+    internal.currentData = {
+        ...result.reconciledState,
+        lineage: {
+            ...result.reconciledState.lineage,
+            sessionId: internal.sessionId,
+        },
+    };
+    internal.issues = result.issues;
+    internal.diffs = result.diffs;
+    internal.resolutions = result.resolutions;
+    if (priorVersion && priorVersion !== view.version) {
+        markAllPendingIntentsAsStale(internal);
+    }
+    autoCheckpoint(internal);
+    runDetachedValueGC(internal);
+    notifySnapshotAndIssueListeners(internal);
+}

package/lib/session.d.ts

@@ -0,0 +1,33 @@
+import type { Session, SessionOptions, SessionFactory } from './types.js';
+/**
+ * Creates a new in-memory session ledger.
+ *
+ * Initializes event log limits, reconciliation behavior, optional persistence,
+ * and optional action handlers.
+ *
+ * @param options Optional session configuration.
+ * @returns A live session instance.
+ */
+export declare function createSession(options?: SessionOptions): Session;
+/**
+ * Recreates a session from serialized data produced by `session.serialize()`.
+ *
+ * @param data Serialized session payload.
+ * @param options Optional runtime overrides (clock, limits, reconciliation, persistence).
+ * @returns A live session instance restored from the payload.
+ */
+export declare function deserialize(data: unknown, options?: SessionOptions): Session;
+/**
+ * Hydrates a session from persistence storage when data exists, otherwise creates a new one.
+ *
+ * If stored data is invalid, it is removed and a fresh session is created.
+ *
+ * @param options Session options including required persistence config.
+ * @returns A hydrated or newly created session.
+ */
+export declare function hydrateOrCreate(options?: SessionOptions): Session;
+/**
+ * Dependency-injection friendly factory for session creation and deserialization.
+ */
+export declare const sessionFactory: SessionFactory;
+//# sourceMappingURL=session.d.ts.map

package/lib/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../packages/session/src/lib/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA2M1E;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAqB/D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAuB5E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAWjE;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAA+C,CAAC"}

package/lib/session.js

@@ -0,0 +1,275 @@
+import { INTERACTION_TYPES } from '@continuum/contract';
+import { createEmptySessionState, generateId, resetSessionState } from './session/session-state.js';
+import { buildSnapshotFromCurrentState, notifySnapshotListeners, subscribeSnapshot, subscribeIssues } from './session/listeners.js';
+import { cloneCheckpointSnapshot, createManualCheckpoint, restoreFromCheckpoint, rewind } from './session/checkpoint-manager.js';
+import { submitIntent, validateIntent, cancelIntent } from './session/intent-manager.js';
+import { recordIntent } from './session/event-log.js';
+import { pushView } from './session/view-pusher.js';
+import { serializeSession, deserializeToState } from './session/serializer.js';
+import { teardownSessionAndClearState } from './session/destroyer.js';
+import { attachPersistence } from './session/persistence.js';
+const DEFAULT_STORAGE_KEY = 'continuum_session';
+const SESSION_DESTROYED_ERROR = 'Session has been destroyed';
+function assertNotDestroyed(internal) {
+    if (internal.destroyed) {
+        throw new Error(SESSION_DESTROYED_ERROR);
+    }
+}
+function applyViewportStateUpdate(internal, nodeId, state) {
+    if (!internal.currentData) {
+        return;
+    }
+    const now = internal.clock();
+    internal.currentData = {
+        ...internal.currentData,
+        viewContext: {
+            ...(internal.currentData.viewContext ?? {}),
+            [nodeId]: state,
+        },
+        lineage: {
+            ...internal.currentData.lineage,
+            timestamp: now,
+        },
+    };
+    const lastAutoCheckpoint = [...internal.checkpoints]
+        .reverse()
+        .find((checkpoint) => checkpoint.trigger === 'auto');
+    if (lastAutoCheckpoint) {
+        const snapshot = buildSnapshotFromCurrentState(internal);
+        if (snapshot) {
+            lastAutoCheckpoint.snapshot = cloneCheckpointSnapshot(snapshot);
+        }
+    }
+    notifySnapshotListeners(internal);
+}
+function assembleSessionFromInternalState(internal, cleanupPersistence) {
+    const session = {
+        get sessionId() { return internal.sessionId; },
+        get isDestroyed() { return internal.destroyed; },
+        getSnapshot() { assertNotDestroyed(internal); return buildSnapshotFromCurrentState(internal); },
+        getIssues() { assertNotDestroyed(internal); return [...internal.issues]; },
+        getDiffs() { assertNotDestroyed(internal); return [...internal.diffs]; },
+        getResolutions() { assertNotDestroyed(internal); return [...internal.resolutions]; },
+        getEventLog() { assertNotDestroyed(internal); return [...internal.eventLog]; },
+        getPendingIntents() { assertNotDestroyed(internal); return [...internal.pendingIntents]; },
+        getDetachedValues() {
+            assertNotDestroyed(internal);
+            return { ...(internal.currentData?.detachedValues ?? {}) };
+        },
+        purgeDetachedValues(filter) {
+            assertNotDestroyed(internal);
+            if (!internal.currentData?.detachedValues)
+                return;
+            if (!filter) {
+                const { detachedValues: _, ...rest } = internal.currentData;
+                internal.currentData = rest;
+            }
+            else {
+                const remaining = {};
+                for (const [key, value] of Object.entries(internal.currentData.detachedValues)) {
+                    if (!filter(key, value)) {
+                        remaining[key] = value;
+                    }
+                }
+                if (Object.keys(remaining).length === 0) {
+                    const { detachedValues: _, ...rest } = internal.currentData;
+                    internal.currentData = rest;
+                }
+                else {
+                    internal.currentData = { ...internal.currentData, detachedValues: remaining };
+                }
+            }
+            notifySnapshotListeners(internal);
+        },
+        proposeValue(nodeId, value, source) {
+            assertNotDestroyed(internal);
+            if (!internal.currentData)
+                return;
+            const existing = internal.currentData.values[nodeId];
+            if (existing && existing.isDirty) {
+                internal.pendingProposals[nodeId] = {
+                    nodeId,
+                    proposedValue: value,
+                    currentValue: existing,
+                    proposedAt: internal.clock(),
+                    source,
+                };
+                notifySnapshotListeners(internal);
+            }
+            else {
+                recordIntent(internal, { nodeId, type: INTERACTION_TYPES.DATA_UPDATE, payload: value });
+                delete internal.pendingProposals[nodeId];
+            }
+        },
+        acceptProposal(nodeId) {
+            assertNotDestroyed(internal);
+            const proposal = internal.pendingProposals[nodeId];
+            if (!proposal)
+                return;
+            recordIntent(internal, {
+                nodeId,
+                type: INTERACTION_TYPES.DATA_UPDATE,
+                payload: { ...proposal.proposedValue, isDirty: true }
+            });
+            delete internal.pendingProposals[nodeId];
+        },
+        rejectProposal(nodeId) {
+            assertNotDestroyed(internal);
+            if (!internal.pendingProposals[nodeId]) {
+                return;
+            }
+            delete internal.pendingProposals[nodeId];
+            notifySnapshotListeners(internal);
+        },
+        getPendingProposals() {
+            assertNotDestroyed(internal);
+            return { ...internal.pendingProposals };
+        },
+        getCheckpoints() { assertNotDestroyed(internal); return [...internal.checkpoints]; },
+        pushView(view) { assertNotDestroyed(internal); pushView(internal, view); },
+        recordIntent(partial) { assertNotDestroyed(internal); recordIntent(internal, partial); },
+        updateState(nodeId, payload) {
+            assertNotDestroyed(internal);
+            recordIntent(internal, { nodeId, type: INTERACTION_TYPES.DATA_UPDATE, payload });
+        },
+        getViewportState(nodeId) {
+            assertNotDestroyed(internal);
+            return internal.currentData?.viewContext?.[nodeId];
+        },
+        updateViewportState(nodeId, state) {
+            assertNotDestroyed(internal);
+            applyViewportStateUpdate(internal, nodeId, state);
+        },
+        submitIntent(partial) { assertNotDestroyed(internal); submitIntent(internal, partial); },
+        validateIntent(intentId) { assertNotDestroyed(internal); return validateIntent(internal, intentId); },
+        cancelIntent(intentId) { assertNotDestroyed(internal); return cancelIntent(internal, intentId); },
+        checkpoint() { assertNotDestroyed(internal); return createManualCheckpoint(internal); },
+        restoreFromCheckpoint(cp) { assertNotDestroyed(internal); restoreFromCheckpoint(internal, cp); },
+        rewind(checkpointId) { assertNotDestroyed(internal); rewind(internal, checkpointId); },
+        reset() {
+            assertNotDestroyed(internal);
+            resetSessionState(internal);
+            notifySnapshotListeners(internal);
+        },
+        onSnapshot(listener) { assertNotDestroyed(internal); return subscribeSnapshot(internal, listener); },
+        onIssues(listener) { assertNotDestroyed(internal); return subscribeIssues(internal, listener); },
+        serialize() { assertNotDestroyed(internal); return serializeSession(internal); },
+        destroy() {
+            assertNotDestroyed(internal);
+            cleanupPersistence?.();
+            return teardownSessionAndClearState(internal);
+        },
+        registerAction(intentId, registration, handler) {
+            assertNotDestroyed(internal);
+            internal.actionRegistry.set(intentId, { registration, handler });
+        },
+        unregisterAction(intentId) {
+            assertNotDestroyed(internal);
+            internal.actionRegistry.delete(intentId);
+        },
+        getRegisteredActions() {
+            assertNotDestroyed(internal);
+            const result = {};
+            for (const [id, entry] of internal.actionRegistry) {
+                result[id] = entry.registration;
+            }
+            return result;
+        },
+        dispatchAction(intentId, nodeId) {
+            assertNotDestroyed(internal);
+            const entry = internal.actionRegistry.get(intentId);
+            if (!entry)
+                return;
+            const snapshot = buildSnapshotFromCurrentState(internal);
+            if (!snapshot)
+                return;
+            return entry.handler({ intentId, snapshot: snapshot.data, nodeId });
+        },
+    };
+    return session;
+}
+/**
+ * Creates a new in-memory session ledger.
+ *
+ * Initializes event log limits, reconciliation behavior, optional persistence,
+ * and optional action handlers.
+ *
+ * @param options Optional session configuration.
+ * @returns A live session instance.
+ */
+export function createSession(options) {
+    const clock = options?.clock ?? Date.now;
+    const internal = createEmptySessionState(generateId('session', clock), clock);
+    internal.maxEventLogSize = options?.maxEventLogSize ?? internal.maxEventLogSize;
+    internal.maxPendingIntents = options?.maxPendingIntents ?? internal.maxPendingIntents;
+    internal.maxCheckpoints = options?.maxCheckpoints ?? internal.maxCheckpoints;
+    internal.reconciliationOptions = options?.reconciliation;
+    internal.validateOnUpdate = options?.validateOnUpdate ?? internal.validateOnUpdate;
+    internal.detachedValuePolicy = options?.detachedValuePolicy;
+    if (options?.actions) {
+        for (const [id, entry] of Object.entries(options.actions)) {
+            internal.actionRegistry.set(id, entry);
+        }
+    }
+    const cleanupPersistence = options?.persistence
+        ? attachPersistence(internal, {
+            ...options.persistence,
+            key: options.persistence.key ?? DEFAULT_STORAGE_KEY,
+        })
+        : undefined;
+    return assembleSessionFromInternalState(internal, cleanupPersistence);
+}
+/**
+ * Recreates a session from serialized data produced by `session.serialize()`.
+ *
+ * @param data Serialized session payload.
+ * @param options Optional runtime overrides (clock, limits, reconciliation, persistence).
+ * @returns A live session instance restored from the payload.
+ */
+export function deserialize(data, options) {
+    const internal = deserializeToState(data, options?.clock ?? Date.now, {
+        maxEventLogSize: options?.maxEventLogSize,
+        maxPendingIntents: options?.maxPendingIntents,
+        maxCheckpoints: options?.maxCheckpoints,
+    });
+    if (options?.reconciliation) {
+        internal.reconciliationOptions = options.reconciliation;
+    }
+    if (options?.validateOnUpdate !== undefined) {
+        internal.validateOnUpdate = options.validateOnUpdate;
+    }
+    const cleanupPersistence = options?.persistence
+        ? attachPersistence(internal, {
+            ...options.persistence,
+            key: options.persistence.key ?? DEFAULT_STORAGE_KEY,
+        })
+        : undefined;
+    return assembleSessionFromInternalState(internal, cleanupPersistence);
+}
+/**
+ * Hydrates a session from persistence storage when data exists, otherwise creates a new one.
+ *
+ * If stored data is invalid, it is removed and a fresh session is created.
+ *
+ * @param options Session options including required persistence config.
+ * @returns A hydrated or newly created session.
+ */
+export function hydrateOrCreate(options) {
+    if (!options?.persistence)
+        return createSession(options);
+    const storageKey = options.persistence.key ?? DEFAULT_STORAGE_KEY;
+    const raw = options.persistence.storage.getItem(storageKey);
+    if (!raw)
+        return createSession(options);
+    try {
+        return deserialize(JSON.parse(raw), options);
+    }
+    catch {
+        options.persistence.storage.removeItem(storageKey);
+        return createSession(options);
+    }
+}
+/**
+ * Dependency-injection friendly factory for session creation and deserialization.
+ */
+export const sessionFactory = { createSession, deserialize };