libpetri 0.3.2

package/dist/petri-net-C3Jy5HCt.d.ts

@@ -0,0 +1,543 @@
+/**
+ * An immutable token carrying a typed value through the Petri net.
+ *
+ * Tokens flow from place to place as transitions fire, carrying typed
+ * payloads that represent the state of a computation or workflow.
+ */
+interface Token<T> {
+    readonly value: T;
+    /** Epoch milliseconds when the token was created. */
+    readonly createdAt: number;
+}
+/** Creates a token with the given value and current timestamp. */
+declare function tokenOf<T>(value: T): Token<T>;
+/**
+ * Returns a unit token (marker with no meaningful value).
+ * Used for pure control flow where presence matters but data doesn't.
+ * Returns a cached singleton whose `value` is `null`.
+ */
+declare function unitToken(): Token<null>;
+/** Creates a token with a specific timestamp (for testing/replay). */
+declare function tokenAt<T>(value: T, createdAt: number): Token<T>;
+/** Checks if this is the singleton unit token. */
+declare function isUnit(token: Token<unknown>): boolean;
+
+/**
+ * A typed place in the Petri Net that holds tokens of a specific type.
+ *
+ * Places are the "state containers" of a Petri net. They hold tokens that
+ * represent data or resources flowing through the net.
+ *
+ * Places use name-based equality (matching Java record semantics).
+ * Internally use `Map<string, ...>` keyed by `place.name` for O(1) lookups.
+ */
+interface Place<T> {
+    readonly name: string;
+    /** Phantom field to carry the type parameter. Never set at runtime. */
+    readonly _phantom?: T;
+}
+/**
+ * An environment place that accepts external token injection.
+ * Wraps a regular Place and marks it for external event injection.
+ */
+interface EnvironmentPlace<T> {
+    readonly place: Place<T>;
+}
+/** Creates a typed place. */
+declare function place<T>(name: string): Place<T>;
+/** Creates an environment place (external event injection point). */
+declare function environmentPlace<T>(name: string): EnvironmentPlace<T>;
+
+/**
+ * Arc types connecting places to transitions in the Petri net.
+ *
+ * | Arc Type  | Requires Token? | Consumes? | Effect                   |
+ * |-----------|-----------------|-----------|--------------------------|
+ * | Input     | Yes             | Yes       | Token consumed on fire   |
+ * | Output    | No              | No        | Token produced on complete|
+ * | Inhibitor | No (blocks)     | No        | Disables transition      |
+ * | Read      | Yes             | No        | Token remains            |
+ * | Reset     | No              | Yes (all) | All tokens removed       |
+ */
+type Arc = ArcInput | ArcOutput | ArcInhibitor | ArcRead | ArcReset;
+interface ArcInput<T = any> {
+    readonly type: 'input';
+    readonly place: Place<T>;
+    readonly guard?: (value: T) => boolean;
+}
+interface ArcOutput<T = any> {
+    readonly type: 'output';
+    readonly place: Place<T>;
+}
+interface ArcInhibitor<T = any> {
+    readonly type: 'inhibitor';
+    readonly place: Place<T>;
+}
+interface ArcRead<T = any> {
+    readonly type: 'read';
+    readonly place: Place<T>;
+}
+interface ArcReset<T = any> {
+    readonly type: 'reset';
+    readonly place: Place<T>;
+}
+/** Input arc: consumes token from place when transition fires. */
+declare function inputArc<T>(place: Place<T>, guard?: (value: T) => boolean): ArcInput<T>;
+/** Output arc: produces token to place when transition fires. */
+declare function outputArc<T>(place: Place<T>): ArcOutput<T>;
+/** Inhibitor arc: blocks transition if place has tokens. */
+declare function inhibitorArc<T>(place: Place<T>): ArcInhibitor<T>;
+/** Read arc: requires token without consuming. */
+declare function readArc<T>(place: Place<T>): ArcRead<T>;
+/** Reset arc: removes all tokens from place when firing. */
+declare function resetArc<T>(place: Place<T>): ArcReset<T>;
+/** Returns the place this arc connects to. */
+declare function arcPlace(arc: Arc): Place<any>;
+/** Checks if an input arc has a guard predicate. */
+declare function hasGuard(arc: ArcInput): boolean;
+/** Checks if a token value matches an input arc's guard. */
+declare function matchesGuard<T>(arc: ArcInput<T>, value: T): boolean;
+
+/**
+ * Input specification with cardinality and optional guard predicate.
+ * CPN-compliant: cardinality determines how many tokens to consume,
+ * guard filters which tokens are eligible.
+ *
+ * Inputs are always AND-joined (all must be satisfied to enable transition).
+ * XOR on inputs is modeled via multiple transitions (conflict).
+ */
+type In = InOne | InExactly | InAll | InAtLeast;
+interface InOne<T = any> {
+    readonly type: 'one';
+    readonly place: Place<T>;
+    readonly guard?: (value: T) => boolean;
+}
+interface InExactly<T = any> {
+    readonly type: 'exactly';
+    readonly place: Place<T>;
+    readonly count: number;
+    readonly guard?: (value: T) => boolean;
+}
+interface InAll<T = any> {
+    readonly type: 'all';
+    readonly place: Place<T>;
+    readonly guard?: (value: T) => boolean;
+}
+interface InAtLeast<T = any> {
+    readonly type: 'at-least';
+    readonly place: Place<T>;
+    readonly minimum: number;
+    readonly guard?: (value: T) => boolean;
+}
+/** Consume exactly 1 token (standard CPN semantics). Optional guard filters eligible tokens. */
+declare function one<T>(place: Place<T>, guard?: (value: T) => boolean): InOne<T>;
+/** Consume exactly N tokens (batching). Optional guard filters eligible tokens. */
+declare function exactly<T>(count: number, place: Place<T>, guard?: (value: T) => boolean): InExactly<T>;
+/** Consume all available tokens (must be 1+). Optional guard filters eligible tokens. */
+declare function all<T>(place: Place<T>, guard?: (value: T) => boolean): InAll<T>;
+/** Wait for N+ tokens, consume all when enabled. Optional guard filters eligible tokens. */
+declare function atLeast<T>(minimum: number, place: Place<T>, guard?: (value: T) => boolean): InAtLeast<T>;
+/** Returns the minimum number of tokens required to enable. */
+declare function requiredCount(spec: In): number;
+/**
+ * Returns the actual number of tokens to consume given the available count.
+ * - One: always consumes 1
+ * - Exactly: always consumes exactly count
+ * - All: consumes all available
+ * - AtLeast: consumes all available (when enabled, i.e., >= minimum)
+ */
+declare function consumptionCount(spec: In, available: number): number;
+
+/**
+ * Output specification with explicit split semantics.
+ * Supports composite structures (XOR of ANDs, AND of XORs, etc.)
+ *
+ * - And: ALL children must receive tokens
+ * - Xor: EXACTLY ONE child receives token
+ * - Place: Leaf node representing a single output place
+ * - Timeout: Timeout branch that activates if action exceeds duration
+ * - ForwardInput: Forward consumed input to output on timeout
+ */
+type Out = OutAnd | OutXor | OutPlace | OutTimeout | OutForwardInput;
+interface OutAnd {
+    readonly type: 'and';
+    readonly children: readonly Out[];
+}
+interface OutXor {
+    readonly type: 'xor';
+    readonly children: readonly Out[];
+}
+interface OutPlace {
+    readonly type: 'place';
+    readonly place: Place<any>;
+}
+interface OutTimeout {
+    readonly type: 'timeout';
+    /** Timeout duration in milliseconds. */
+    readonly afterMs: number;
+    readonly child: Out;
+}
+interface OutForwardInput {
+    readonly type: 'forward-input';
+    readonly from: Place<any>;
+    readonly to: Place<any>;
+}
+/**
+ * AND-split: all children must receive tokens.
+ *
+ * @example
+ * ```ts
+ * // AND of XOR branches: one of (A,B) AND one of (C,D)
+ * and(xorPlaces(placeA, placeB), xorPlaces(placeC, placeD))
+ *
+ * // AND with a fixed place + XOR branch
+ * and(outPlace(always), xorPlaces(left, right))
+ * ```
+ */
+declare function and(...children: Out[]): OutAnd;
+/** AND-split from places: all places must receive tokens. */
+declare function andPlaces(...places: Place<any>[]): OutAnd;
+/** XOR-split: exactly one child receives token. */
+declare function xor(...children: Out[]): OutXor;
+/** XOR-split from places: exactly one place receives token. */
+declare function xorPlaces(...places: Place<any>[]): OutXor;
+/** Leaf output spec for a single place. */
+declare function outPlace(p: Place<any>): OutPlace;
+/** Timeout output: activates if action exceeds duration. */
+declare function timeout(afterMs: number, child: Out): OutTimeout;
+/** Timeout output pointing to a single place. */
+declare function timeoutPlace(afterMs: number, p: Place<any>): OutTimeout;
+/** Forward consumed input value to output place on timeout. */
+declare function forwardInput(from: Place<any>, to: Place<any>): OutForwardInput;
+/** Collects all leaf places from this output spec (flattened). */
+declare function allPlaces(out: Out): Set<Place<any>>;
+/**
+ * Enumerates all possible output branches for structural analysis.
+ *
+ * - AND = single branch containing all child places (Cartesian product)
+ * - XOR = one branch per alternative child
+ * - Nested = Cartesian product for AND, union for XOR
+ */
+declare function enumerateBranches(out: Out): ReadonlyArray<ReadonlySet<Place<any>>>;
+
+/**
+ * Firing timing specification for transitions.
+ *
+ * Based on classical Time Petri Net (TPN) semantics:
+ * - Transition CANNOT fire before earliest time (lower bound)
+ * - Transition MUST fire by deadline OR become disabled (upper bound)
+ *
+ * All durations are in milliseconds.
+ */
+type Timing = TimingImmediate | TimingDeadline | TimingDelayed | TimingWindow | TimingExact;
+interface TimingImmediate {
+    readonly type: 'immediate';
+}
+interface TimingDeadline {
+    readonly type: 'deadline';
+    /** Deadline in milliseconds. Must be positive. */
+    readonly byMs: number;
+}
+interface TimingDelayed {
+    readonly type: 'delayed';
+    /** Minimum delay in milliseconds. Must be non-negative. */
+    readonly afterMs: number;
+}
+interface TimingWindow {
+    readonly type: 'window';
+    /** Earliest firing time in milliseconds. Must be non-negative. */
+    readonly earliestMs: number;
+    /** Latest firing time in milliseconds. Must be >= earliestMs. */
+    readonly latestMs: number;
+}
+interface TimingExact {
+    readonly type: 'exact';
+    /** Exact firing time in milliseconds. Must be non-negative. */
+    readonly atMs: number;
+}
+/** ~100 years in milliseconds, used for "unconstrained" intervals. */
+declare const MAX_DURATION_MS: number;
+/** Immediate firing: can fire as soon as enabled, no deadline. [0, inf) */
+declare function immediate(): TimingImmediate;
+/** Immediate with deadline: can fire immediately, must fire by deadline. [0, by] */
+declare function deadline(byMs: number): TimingDeadline;
+/** Delayed firing: must wait, then can fire anytime. [after, inf) */
+declare function delayed(afterMs: number): TimingDelayed;
+/** Time window: can fire within [earliest, latest]. */
+declare function window(earliestMs: number, latestMs: number): TimingWindow;
+/** Exact timing: fires at precisely the specified time. [at, at] */
+declare function exact(atMs: number): TimingExact;
+/** Returns the earliest time (ms) the transition can fire after enabling. */
+declare function earliest(timing: Timing): number;
+/** Returns the latest time (ms) by which the transition must fire. */
+declare function latest(timing: Timing): number;
+/** Returns true if this timing has a finite deadline. */
+declare function hasDeadline(timing: Timing): boolean;
+
+/**
+ * Consumed input tokens bound to their source places.
+ *
+ * Passed to TransitionAction as the `input` parameter, providing
+ * type-safe read access to tokens consumed from input places.
+ */
+declare class TokenInput {
+    private readonly tokens;
+    /** Add a token (used by executor when firing transition). */
+    add<T>(place: Place<T>, token: Token<T>): this;
+    /** Get all tokens for a place. */
+    getAll<T>(place: Place<T>): readonly Token<T>[];
+    /** Get the first token for a place. Throws if no tokens. */
+    get<T>(place: Place<T>): Token<T>;
+    /** Get the first token's value for a place. Throws if no tokens. */
+    value<T>(place: Place<T>): T;
+    /** Get all token values for a place. */
+    values<T>(place: Place<T>): readonly T[];
+    /** Get token count for a place. */
+    count(place: Place<any>): number;
+    /** Check if any tokens exist for a place. */
+    has(place: Place<any>): boolean;
+}
+
+/**
+ * An output entry: place + token pair.
+ */
+interface OutputEntry {
+    readonly place: Place<any>;
+    readonly token: Token<any>;
+}
+/**
+ * Collects output tokens produced by a transition action.
+ */
+declare class TokenOutput {
+    private readonly _entries;
+    /** Add a value to an output place (creates token with current timestamp). */
+    add<T>(place: Place<T>, value: T): this;
+    /** Add a pre-existing token to an output place. */
+    addToken<T>(place: Place<T>, token: Token<T>): this;
+    /** Returns all collected outputs. */
+    entries(): readonly OutputEntry[];
+    /** Check if any outputs were produced. */
+    isEmpty(): boolean;
+    /** Returns the set of place names that received tokens. */
+    placesWithTokens(): Set<string>;
+}
+
+/** Callback for emitting log messages from transition actions. */
+type LogFn = (level: string, message: string, error?: Error) => void;
+/**
+ * Context provided to transition actions.
+ *
+ * Provides filtered access based on structure:
+ * - Input places (consumed tokens)
+ * - Read places (context tokens, not consumed)
+ * - Output places (where to produce tokens)
+ *
+ * Enforces the structure contract — actions can only access places
+ * declared in the transition's structure.
+ */
+declare class TransitionContext {
+    private readonly rawInput;
+    private readonly _rawOutput;
+    private readonly allowedInputs;
+    private readonly allowedReads;
+    private readonly allowedOutputs;
+    private readonly _inputPlaces;
+    private readonly _readPlaces;
+    private readonly _outputPlaces;
+    private readonly _transitionName;
+    private readonly executionCtx;
+    private readonly _logFn?;
+    constructor(transitionName: string, rawInput: TokenInput, rawOutput: TokenOutput, inputPlaces: ReadonlySet<Place<any>>, readPlaces: ReadonlySet<Place<any>>, outputPlaces: ReadonlySet<Place<any>>, executionContext?: Map<string, unknown>, logFn?: LogFn);
+    /** Get single consumed input value. Throws if place not declared or multiple tokens. */
+    input<T>(place: Place<T>): T;
+    /** Get all consumed input values for a place. */
+    inputs<T>(place: Place<T>): readonly T[];
+    /** Get consumed input token with metadata. */
+    inputToken<T>(place: Place<T>): Token<T>;
+    /** Returns declared input places (consumed). */
+    inputPlaces(): ReadonlySet<Place<any>>;
+    private requireInput;
+    /** Get read-only context value. Throws if place not declared as read. */
+    read<T>(place: Place<T>): T;
+    /** Get all read-only context values for a place. */
+    reads<T>(place: Place<T>): readonly T[];
+    /** Returns declared read places (context, not consumed). */
+    readPlaces(): ReadonlySet<Place<any>>;
+    private requireRead;
+    /** Add output value. Throws if place not declared as output. */
+    output<T>(place: Place<T>, value: T): this;
+    /** Add output token with metadata. */
+    outputToken<T>(place: Place<T>, token: Token<T>): this;
+    /** Returns declared output places. */
+    outputPlaces(): ReadonlySet<Place<any>>;
+    private requireOutput;
+    /** Returns the transition name. */
+    transitionName(): string;
+    /** Retrieves an execution context object by key. */
+    executionContext<T>(key: string): T | undefined;
+    /** Checks if an execution context object of the given key is present. */
+    hasExecutionContext(key: string): boolean;
+    /** Emits a structured log message into the event store. */
+    log(level: string, message: string, error?: Error): void;
+    /** @internal Used by BitmapNetExecutor to collect outputs after action completion. */
+    rawOutput(): TokenOutput;
+}
+
+/**
+ * The action executed when a transition fires.
+ * Receives a TransitionContext providing filtered I/O and structure access.
+ */
+type TransitionAction = (ctx: TransitionContext) => Promise<void>;
+/** Identity action: produces no outputs. */
+declare function passthrough(): TransitionAction;
+/**
+ * Transform action: applies function to context, copies result to ALL output places.
+ *
+ * @example
+ * ```ts
+ * const action = transform(ctx => ctx.input(inputPlace).toUpperCase());
+ * // Result is copied to every declared output place
+ * ```
+ */
+declare function transform(fn: (ctx: TransitionContext) => unknown): TransitionAction;
+/**
+ * Fork action: copies single input token to all outputs.
+ * Requires exactly one input place (derived from structure).
+ */
+declare function fork(): TransitionAction;
+/**
+ * Transform with explicit input place.
+ */
+declare function transformFrom<I>(inputPlace: Place<I>, fn: (value: I) => unknown): TransitionAction;
+/**
+ * Async transform: applies async function, copies result to all outputs.
+ */
+declare function transformAsync(fn: (ctx: TransitionContext) => Promise<unknown>): TransitionAction;
+/** Produce action: produces a single token with the given value to the specified place. */
+declare function produce<T>(place: Place<T>, value: T): TransitionAction;
+/**
+ * Wraps an action with timeout handling.
+ * If the action completes within the timeout, normal completion.
+ * If the timeout expires, the timeoutValue is produced to the timeoutPlace.
+ *
+ * @example
+ * ```ts
+ * const action = withTimeout(
+ *   async (ctx) => { ctx.output(resultPlace, await fetchData()); },
+ *   5000,
+ *   timeoutPlace,
+ *   'timed-out',
+ * );
+ * ```
+ */
+declare function withTimeout<T>(action: TransitionAction, timeoutMs: number, timeoutPlace: Place<T>, timeoutValue: T): TransitionAction;
+
+/**
+ * A transition in the Time Petri Net that transforms tokens.
+ *
+ * Transitions use identity-based equality (===) — each instance is unique
+ * regardless of name. The name is purely a label for display/debugging/export.
+ */
+declare class Transition {
+    readonly name: string;
+    readonly inputSpecs: readonly In[];
+    readonly outputSpec: Out | null;
+    readonly inhibitors: readonly ArcInhibitor[];
+    readonly reads: readonly ArcRead[];
+    readonly resets: readonly ArcReset[];
+    readonly timing: Timing;
+    readonly actionTimeout: OutTimeout | null;
+    readonly action: TransitionAction;
+    readonly priority: number;
+    private readonly _inputPlaces;
+    private readonly _readPlaces;
+    private readonly _outputPlaces;
+    /** @internal Use {@link Transition.builder} to create instances. */
+    constructor(key: symbol, name: string, inputSpecs: readonly In[], outputSpec: Out | null, inhibitors: readonly ArcInhibitor[], reads: readonly ArcRead[], resets: readonly ArcReset[], timing: Timing, action: TransitionAction, priority: number);
+    /** Returns set of input places — consumed tokens. */
+    inputPlaces(): ReadonlySet<Place<any>>;
+    /** Returns set of read places — context tokens, not consumed. */
+    readPlaces(): ReadonlySet<Place<any>>;
+    /** Returns set of output places — where tokens are produced. */
+    outputPlaces(): ReadonlySet<Place<any>>;
+    /** Returns true if this transition has an action timeout. */
+    hasActionTimeout(): boolean;
+    toString(): string;
+    static builder(name: string): TransitionBuilder;
+}
+declare class TransitionBuilder {
+    private readonly _name;
+    private readonly _inputSpecs;
+    private _outputSpec;
+    private readonly _inhibitors;
+    private readonly _reads;
+    private readonly _resets;
+    private _timing;
+    private _action;
+    private _priority;
+    constructor(name: string);
+    /** Add input specifications with cardinality. */
+    inputs(...specs: In[]): this;
+    /** Set the output specification (composite AND/XOR structure). */
+    outputs(spec: Out): this;
+    /** Add inhibitor arc. */
+    inhibitor(place: Place<any>): this;
+    /** Add inhibitor arcs. */
+    inhibitors(...places: Place<any>[]): this;
+    /** Add read arc. */
+    read(place: Place<any>): this;
+    /** Add read arcs. */
+    reads(...places: Place<any>[]): this;
+    /** Add reset arc. */
+    reset(place: Place<any>): this;
+    /** Add reset arcs. */
+    resets(...places: Place<any>[]): this;
+    /** Set timing specification. */
+    timing(timing: Timing): this;
+    /** Set the transition action. */
+    action(action: TransitionAction): this;
+    /** Set the priority (higher fires first). */
+    priority(priority: number): this;
+    build(): Transition;
+}
+
+/**
+ * Immutable definition of a Time Petri Net structure.
+ *
+ * A PetriNet is a reusable definition that can be executed multiple times
+ * with different initial markings. Places are auto-collected from transitions.
+ */
+declare class PetriNet {
+    readonly name: string;
+    readonly places: ReadonlySet<Place<any>>;
+    readonly transitions: ReadonlySet<Transition>;
+    /** @internal Use {@link PetriNet.builder} to create instances. */
+    constructor(key: symbol, name: string, places: ReadonlySet<Place<any>>, transitions: ReadonlySet<Transition>);
+    /**
+     * Creates a new PetriNet with actions bound to transitions by name.
+     * Unbound transitions keep passthrough action.
+     */
+    bindActions(actionBindings: Map<string, TransitionAction> | Record<string, TransitionAction>): PetriNet;
+    /**
+     * Creates a new PetriNet with actions bound via a resolver function.
+     */
+    bindActionsWithResolver(actionResolver: (name: string) => TransitionAction): PetriNet;
+    static builder(name: string): PetriNetBuilder;
+}
+declare class PetriNetBuilder {
+    private readonly _name;
+    private readonly _places;
+    private readonly _transitions;
+    constructor(name: string);
+    /** Add an explicit place. */
+    place(place: Place<any>): this;
+    /** Add explicit places. */
+    places(...places: Place<any>[]): this;
+    /** Add a transition (auto-collects places from arcs). */
+    transition(transition: Transition): this;
+    /** Add transitions (auto-collects places from arcs). */
+    transitions(...transitions: Transition[]): this;
+    build(): PetriNet;
+}
+
+export { hasDeadline as $, type Arc as A, TokenOutput as B, type TransitionAction as C, TransitionBuilder as D, type EnvironmentPlace as E, all as F, allPlaces as G, and as H, type In as I, andPlaces as J, arcPlace as K, type LogFn as L, MAX_DURATION_MS as M, atLeast as N, type Out as O, type Place as P, consumptionCount as Q, deadline as R, delayed as S, type Token as T, earliest as U, enumerateBranches as V, environmentPlace as W, exact as X, exactly as Y, fork as Z, forwardInput as _, PetriNet as a, hasGuard as a0, immediate as a1, inhibitorArc as a2, inputArc as a3, isUnit as a4, latest as a5, matchesGuard as a6, one as a7, outPlace as a8, outputArc as a9, passthrough as aa, place as ab, produce as ac, readArc as ad, requiredCount as ae, resetArc as af, timeout as ag, timeoutPlace as ah, tokenAt as ai, tokenOf as aj, transform as ak, transformAsync as al, transformFrom as am, unitToken as an, window as ao, withTimeout as ap, xor as aq, xorPlaces as ar, Transition as b, TransitionContext as c, type ArcInhibitor as d, type ArcInput as e, type ArcOutput as f, type ArcRead as g, type ArcReset as h, type InAll as i, type InAtLeast as j, type InExactly as k, type InOne as l, type OutAnd as m, type OutForwardInput as n, type OutPlace as o, type OutTimeout as p, type OutXor as q, type OutputEntry as r, PetriNetBuilder as s, type Timing as t, type TimingDeadline as u, type TimingDelayed as v, type TimingExact as w, type TimingImmediate as x, type TimingWindow as y, TokenInput as z };