@zhin.js/plugin-runtime 1.1.6 → 1.1.7

package/lib/root-controller.d.ts

@@ -1,29 +1,30 @@
 import type { PluginId } from './identity.js';
-import { type PreparedGeneration, type RuntimeSnapshot, type SnapshotReader, type SnapshotState } from './snapshot.js';
+import { type CommittedGeneration, type PreparedGeneration, type RuntimeSnapshot, type SnapshotReader, type SnapshotState } from './snapshot.js';
 export type RootState = 'idle' | 'running' | 'stopping' | 'stopped' | 'failed';
-export type PrepareGeneration = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration | Promise<PreparedGeneration>;
-export type PrepareTransaction = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration | undefined | Promise<PreparedGeneration | undefined>;
+export type PrepareGeneration<TState = undefined> = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration<TState> | Promise<PreparedGeneration<TState>>;
+export type PrepareTransaction<TState = undefined> = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration<TState> | undefined | Promise<PreparedGeneration<TState> | undefined>;
 export type ControlErrorHandler = (error: unknown) => void;
-export interface GenerationCommitEvent {
-    readonly previous: RuntimeSnapshot;
-    readonly current: RuntimeSnapshot;
+export interface GenerationCommitEvent<TState = undefined> {
+    readonly previous: CommittedGeneration<TState>;
+    readonly current: CommittedGeneration<TState>;
 }
-export type GenerationCommitListener = (event: GenerationCommitEvent) => void;
+export type GenerationCommitListener<TState = undefined> = (event: GenerationCommitEvent<TState>) => void | Promise<void>;
 export declare class RootIntegrityError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
-export declare class RootController {
+export declare class RootController<TState = undefined> {
     #private;
     private readonly onControlError;
     readonly snapshots: SnapshotReader;
-    constructor(initial: SnapshotState, onControlError?: ControlErrorHandler);
+    constructor(initial: SnapshotState, onControlError?: ControlErrorHandler, ...state: [TState] extends [undefined] ? [initialState?: undefined] : [initialState: TState]);
     get state(): RootState;
     get generation(): number;
     get snapshot(): RuntimeSnapshot;
+    get committed(): CommittedGeneration<TState>;
     /** Observe successful generation commits, including the initial start. */
-    onGenerationCommit(listener: GenerationCommitListener): () => void;
-    start(prepare: PrepareGeneration): Promise<RuntimeSnapshot>;
-    transact(prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
-    reload(_target: PluginId | string, prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
+    onGenerationCommit(listener: GenerationCommitListener<TState>): () => void;
+    start(prepare: PrepareGeneration<TState>): Promise<RuntimeSnapshot>;
+    transact(prepare: PrepareTransaction<TState>): Promise<RuntimeSnapshot>;
+    reload(_target: PluginId | string, prepare: PrepareTransaction<TState>): Promise<RuntimeSnapshot>;
     stop(): Promise<void>;
 }

package/lib/root-controller.js

@@ -16,9 +16,9 @@ export class RootController {
     #stopRequested = false;
     #activeTransaction;
     #generationCommitListeners = new Set();
-    constructor(initial, onControlError = () => undefined) {
+    constructor(initial, onControlError = () => undefined, ...state) {
         this.onControlError = onControlError;
-        this.#snapshotStore = new SnapshotStore(initial, (error) => this.#failIntegrity(error));
+        this.#snapshotStore = new SnapshotStore(initial, (error) => this.#failIntegrity(error), ...state);
         const store = this.#snapshotStore;
         this.snapshots = Object.freeze({
             acquire: () => {
@@ -39,6 +39,9 @@ export class RootController {
     get snapshot() {
         return this.#snapshotStore.current;
     }
+    get committed() {
+        return this.#snapshotStore.committed;
+    }
     /** Observe successful generation commits, including the initial start. */
     onGenerationCommit(listener) {
         this.#generationCommitListeners.add(listener);
@@ -141,21 +144,23 @@ export class RootController {
         return result;
     }
     #commitGeneration(expectedGeneration, prepared) {
-        const previous = this.#snapshotStore.current;
-        const snapshot = this.#snapshotStore.commit(expectedGeneration, prepared);
-        const event = Object.freeze({ previous, current: snapshot });
+        const previous = this.#snapshotStore.committed;
+        const current = this.#snapshotStore.commit(expectedGeneration, prepared);
+        const event = Object.freeze({ previous, current });
         const listeners = [...this.#generationCommitListeners];
         queueMicrotask(() => {
             for (const listener of listeners) {
                 try {
-                    listener(event);
+                    void Promise.resolve(listener(event)).catch((error) => {
+                        this.#reportControlError(error);
+                    });
                 }
                 catch (error) {
                     this.#reportControlError(error);
                 }
             }
         });
-        return snapshot;
+        return current.snapshot;
     }
     #reportControlError(error) {
         try {

package/lib/snapshot.d.ts

@@ -22,11 +22,20 @@ export interface RuntimeSnapshot {
     readonly projections: ReadonlyMap<FeatureId, unknown>;
 }
 export type SnapshotState = Omit<RuntimeSnapshot, 'generation'>;
-export interface PreparedGeneration {
+interface PreparedGenerationBase {
     readonly snapshot: SnapshotState;
     readonly dispose: Dispose;
     readonly handoff?: GenerationHandoff;
 }
+export type PreparedGeneration<TState = undefined> = PreparedGenerationBase & ([TState] extends [undefined] ? {
+    readonly state?: undefined;
+} : {
+    readonly state: TState;
+});
+export interface CommittedGeneration<TState = undefined> {
+    readonly snapshot: RuntimeSnapshot;
+    readonly state: TState;
+}
 export declare class GenerationConflictError extends Error {
     readonly expected: number;
     readonly actual: number;
@@ -46,14 +55,16 @@ export interface SnapshotReader {
     acquire(): SnapshotLease;
     owns(lease: SnapshotLease): boolean;
 }
-export declare class SnapshotStore implements SnapshotReader {
+export declare class SnapshotStore<TState = undefined> implements SnapshotReader {
     #private;
     private readonly onDisposalError;
-    constructor(initial: SnapshotState, onDisposalError?: (error: unknown) => void);
+    constructor(initial: SnapshotState, onDisposalError?: (error: unknown) => void, ...state: [TState] extends [undefined] ? [initialState?: undefined] : [initialState: TState]);
     get current(): RuntimeSnapshot;
+    /** Complete active record; snapshot and state always belong to one generation. */
+    get committed(): CommittedGeneration<TState>;
     acquire(): SnapshotLease;
     owns(lease: SnapshotLease): boolean;
-    commit(expectedGeneration: number, prepared: PreparedGeneration): RuntimeSnapshot;
+    commit(expectedGeneration: number, prepared: PreparedGeneration<TState>): CommittedGeneration<TState>;
     close(): Promise<void>;
 }
 export declare function createSnapshotView(generation: number, state: SnapshotState): RuntimeSnapshot;

package/lib/snapshot.js

@@ -36,12 +36,16 @@ export class SnapshotStore {
     #retired = new Set();
     #leases = new WeakSet();
     #closed = false;
-    constructor(initial, onDisposalError = () => undefined) {
+    constructor(initial, onDisposalError = () => undefined, ...state) {
         this.onDisposalError = onDisposalError;
+        const initialState = state[0];
         const snapshot = createSnapshotView(0, initial);
+        const committed = Object.freeze({ snapshot, state: initialState });
         const admissions = collectSnapshotAdmissions(snapshot);
         const record = {
             snapshot,
+            state: initialState,
+            committed,
             dispose: () => undefined,
             admissions,
             leases: 0,
@@ -53,6 +57,10 @@ export class SnapshotStore {
     get current() {
         return this.#current.snapshot;
     }
+    /** Complete active record; snapshot and state always belong to one generation. */
+    get committed() {
+        return this.#current.committed;
+    }
     acquire() {
         if (this.#closed)
             throw new Error('SnapshotStore is closed');
@@ -75,9 +83,13 @@ export class SnapshotStore {
         }
         const previous = this.#current;
         const snapshot = createSnapshotView(expectedGeneration + 1, prepared.snapshot);
+        const state = prepared.state;
+        const committed = Object.freeze({ snapshot, state });
         const admissions = collectSnapshotAdmissions(snapshot);
         const next = {
             snapshot,
+            state,
+            committed,
             dispose: prepared.dispose,
             admissions,
             leases: 0,
@@ -90,7 +102,7 @@ export class SnapshotStore {
         previous.retired = true;
         this.#retired.add(previous);
         this.#disposeIfReady(previous);
-        return this.#current.snapshot;
+        return this.#current.committed;
     }
     async close() {
         if (this.#closed)

package/lib/token.d.ts

@@ -6,6 +6,7 @@ export interface Token<T> {
     readonly _type?: () => T;
 }
 export declare function createToken<T>(id: string, description?: string): Token<T>;
+export declare function createRootPrivateToken<T>(id: string, description?: string): Token<T>;
 export declare class Scope {
     #private;
     readonly owner: PluginId;

package/lib/token.js

@@ -1,8 +1,14 @@
 import { DisposeStack } from './dispose.js';
 import { tokenId } from './identity.js';
+const rootPrivateTokens = new WeakSet();
 export function createToken(id, description) {
     return Object.freeze({ id: tokenId(id), description });
 }
+export function createRootPrivateToken(id, description) {
+    const token = { id: tokenId(id), description };
+    rootPrivateTokens.add(token);
+    return Object.freeze(token);
+}
 export class Scope {
     owner;
     parent;
@@ -20,20 +26,36 @@ export class Scope {
         if (this.#bindings.has(token.id)) {
             throw new Error(`Duplicate resource ${token.id} in ${this.owner}`);
         }
-        this.#bindings.set(token.id, Object.freeze({ owner: this.owner, value }));
+        this.#bindings.set(token.id, Object.freeze({
+            owner: this.owner,
+            value,
+            rootPrivate: rootPrivateTokens.has(token),
+            token,
+        }));
         if (dispose)
             this.disposers.add(dispose);
     }
     use(token) {
         const binding = this.#bindings.get(token.id);
-        if (binding)
-            return binding.value;
-        if (this.parent)
-            return this.parent.use(token);
+        if (binding) {
+            if (!binding.rootPrivate || binding.token === token)
+                return binding.value;
+            throw new Error(`Missing resource ${token.id} for ${this.owner}`);
+        }
+        const inherited = this.parent
+            ? this.parent.#resolveForDescendant(token.id)
+            : undefined;
+        if (inherited?.status === 'found')
+            return inherited.binding.value;
         throw new Error(`Missing resource ${token.id} for ${this.owner}`);
     }
     has(token) {
-        return this.#bindings.has(token.id) || Boolean(this.parent?.has(token));
+        const binding = this.#bindings.get(token.id);
+        if (binding)
+            return !binding.rootPrivate || binding.token === token;
+        return this.parent
+            ? this.parent.#resolveForDescendant(token.id)?.status === 'found'
+            : false;
     }
     seal() {
         this.#sealed = true;
@@ -45,8 +67,19 @@ export class Scope {
         const result = this.parent
             ? new Map(this.parent.snapshot())
             : new Map();
-        for (const [id, binding] of this.#bindings)
-            result.set(id, binding.value);
+        for (const [id, binding] of this.#bindings) {
+            if (!binding.rootPrivate)
+                result.set(id, binding.value);
+        }
         return result;
     }
+    #resolveForDescendant(id) {
+        const binding = this.#bindings.get(id);
+        if (binding) {
+            return binding.rootPrivate
+                ? Object.freeze({ status: 'blocked' })
+                : Object.freeze({ status: 'found', binding });
+        }
+        return this.parent ? this.parent.#resolveForDescendant(id) : undefined;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",