@superdurable/dex 0.1.3 → 0.1.5

package/dist/src/persistence.d.ts

@@ -1,45 +1,160 @@
 import type { Channel, ChannelMap } from "./wait.js";
 import type { Codec } from "./codec.js";
 import type { Context } from "./context.js";
+/** Selects how Dex indexes an Attribute for Flow search. */
 export declare const IndexType: Readonly<{
+    /** Indexes an exact string value. */
     readonly KEYWORD: "keyword";
+    /** Indexes a string for tokenized full-text matching. */
     readonly FULL_TEXT: "fullText";
+    /** Indexes every string in an array as a keyword. */
     readonly KEYWORD_ARRAY: "keywordArray";
+    /** Indexes a signed 64-bit integer. */
     readonly INT: "int";
+    /** Indexes a finite floating-point number. */
     readonly DOUBLE: "double";
+    /** Indexes a Boolean value. */
     readonly BOOL: "bool";
+    /** Indexes a JavaScript Date value. */
     readonly DATETIME: "datetime";
 }>;
+/** Represents a value from {@link IndexType}. */
 export type IndexType = (typeof IndexType)[keyof typeof IndexType];
+/** Configures the search index for an Attribute or AttributeMap. */
 export interface AttributeIndex {
+    /** Value representation accepted by the search index. */
     readonly type: IndexType;
+    /** Physical search key; indexed AttributeMaps require an explicit key. */
     readonly indexKey?: string;
 }
+/** Describes an Attribute lock acquired for a Step or RPC handler. */
 export interface AttributeLock {
+    /** Singleton Attribute or AttributeMap definition to lock. */
     readonly attribute: Attribute<unknown> | AttributeMap<unknown>;
+    /** AttributeMap instance; omitted for a singleton Attribute. */
     readonly instance?: string;
 }
+/**
+ * Defines a typed, durable singleton value owned by a Flow.
+ *
+ * @example
+ * ```ts
+ * const status = new Attribute("status", stringCodec, {
+ *   type: IndexType.KEYWORD,
+ * });
+ * const persistence: PersistenceSchema = { attributes: [status] };
+ * ```
+ * @typeParam T - Value encoded by the Attribute's codec.
+ */
 export declare class Attribute<T> {
     readonly name: string;
     readonly codec: Codec<T>;
     readonly index?: AttributeIndex | undefined;
+    /**
+     * Creates an Attribute definition for a PersistenceSchema.
+     * @param name - Non-empty logical name unique within the Flow.
+     * @param codec - Value codec used by handlers and Client calls.
+     * @param index - Optional visibility search index.
+     */
     constructor(name: string, codec: Codec<T>, index?: AttributeIndex | undefined);
+    /**
+     * Reads the current value from handler decision state.
+     * @param context - Current Step or RPC Context.
+     * @returns The decoded Attribute value.
+     */
     get(context: Context): T;
+    /**
+     * Stages a value to persist with the current decision.
+     * @param context - Current Step or RPC Context.
+     * @param value - Typed value to persist.
+     */
     set(context: Context, value: T): void;
+    /**
+     * Stages deletion in the current decision.
+     * @param context - Current Step or RPC Context.
+     */
     delete(context: Context): void;
+    /**
+     * Returns an immutable Attribute definition whose writes are projected to the Flow's Attribute Store.
+     *
+     * Projection is asynchronous and latest-state only. Deletion writes SQL `NULL`, projection failures do
+     * not roll back Flow Attribute writes, and the Flow must select a configured Attribute Store name.
+     * @returns A new synced definition; this definition remains unchanged.
+     */
+    syncToAttributeStore(): Attribute<T>;
+    /**
+     * Creates a lock request for this Attribute.
+     * @returns A lock for this singleton Attribute.
+     */
     lock(): AttributeLock;
 }
+/**
+ * Defines a typed family of durable values keyed by map instance.
+ * @typeParam T - Value encoded for every map instance.
+ */
 export declare class AttributeMap<T> {
     readonly name: string;
     readonly codec: Codec<T>;
     readonly index?: AttributeIndex | undefined;
+    /**
+     * Creates an AttributeMap definition for a PersistenceSchema.
+     * @param name - Non-empty logical name unique within the Flow.
+     * @param codec - Value codec shared by every instance.
+     * @param index - Optional shared visibility search index.
+     */
     constructor(name: string, codec: Codec<T>, index?: AttributeIndex | undefined);
+    /**
+     * Reads one map instance from handler decision state.
+     * @param context - Current Step or RPC Context.
+     * @param instance - Non-empty logical map key.
+     * @returns The decoded instance value.
+     */
     get(context: Context, instance: string): T;
+    /**
+     * Stages one map-instance write.
+     * @param context - Current Step or RPC Context.
+     * @param instance - Non-empty logical map key.
+     * @param value - Typed value to persist.
+     */
     set(context: Context, instance: string, value: T): void;
+    /**
+     * Stages deletion of one map instance.
+     * @param context - Current Step or RPC Context.
+     * @param instance - Non-empty logical map key.
+     */
     delete(context: Context, instance: string): void;
+    /**
+     * Returns the number of existing instances, including buffered writes.
+     * @param context - Current Step or RPC Context.
+     * @returns The number of keys visible after decision-local writes and deletions.
+     */
+    getMapSize(context: Context): number;
+    /**
+     * Returns decoded existing instance keys in ascending order.
+     * @param context - Current Step or RPC Context.
+     * @returns Keys visible after decision-local writes and deletions.
+     */
+    getAllInstanceKeys(context: Context): readonly string[];
+    /**
+     * Returns an immutable AttributeMap definition whose writes are projected to the Flow's Attribute Store.
+     *
+     * Projection is asynchronous and latest-state only. Each map instance uses its physical Attribute name.
+     * Deletion writes SQL `NULL`, projection failures do not roll back Flow Attribute writes, and the Flow
+     * must select a configured Attribute Store name.
+     * @returns A new synced definition; this definition remains unchanged.
+     */
+    syncToAttributeStore(): AttributeMap<T>;
+    /**
+     * Creates a lock request scoped to one map instance.
+     * @param instance - Non-empty logical map key.
+     * @returns A lock for the requested instance.
+     */
     lock(instance: string): AttributeLock;
 }
+/** Declares the Attributes and Channels owned by a Flow type. */
 export interface PersistenceSchema {
+    /** Singleton and map Attribute definitions with unique names. */
     readonly attributes?: readonly (Attribute<unknown> | AttributeMap<unknown>)[];
+    /** Singleton and map Channel definitions with unique names. */
     readonly channels?: readonly (Channel<unknown> | ChannelMap<unknown>)[];
 }

package/dist/src/persistence.js

@@ -5,58 +5,172 @@
 // See the LICENSE file in the repository root.
 //
 // SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
+import { markAttributeStoreSynced } from "./attribute-store-sync.js";
 import { requireName } from "./validation.js";
+/** Selects how Dex indexes an Attribute for Flow search. */
 export const IndexType = Object.freeze({
+    /** Indexes an exact string value. */
     KEYWORD: "keyword",
+    /** Indexes a string for tokenized full-text matching. */
     FULL_TEXT: "fullText",
+    /** Indexes every string in an array as a keyword. */
     KEYWORD_ARRAY: "keywordArray",
+    /** Indexes a signed 64-bit integer. */
     INT: "int",
+    /** Indexes a finite floating-point number. */
     DOUBLE: "double",
+    /** Indexes a Boolean value. */
     BOOL: "bool",
+    /** Indexes a JavaScript Date value. */
     DATETIME: "datetime",
 });
+/**
+ * Defines a typed, durable singleton value owned by a Flow.
+ *
+ * @example
+ * ```ts
+ * const status = new Attribute("status", stringCodec, {
+ *   type: IndexType.KEYWORD,
+ * });
+ * const persistence: PersistenceSchema = { attributes: [status] };
+ * ```
+ * @typeParam T - Value encoded by the Attribute's codec.
+ */
 export class Attribute {
     name;
     codec;
     index;
+    /**
+     * Creates an Attribute definition for a PersistenceSchema.
+     * @param name - Non-empty logical name unique within the Flow.
+     * @param codec - Value codec used by handlers and Client calls.
+     * @param index - Optional visibility search index.
+     */
     constructor(name, codec, index) {
         this.name = name;
         this.codec = codec;
         this.index = index;
         requireName(name);
     }
+    /**
+     * Reads the current value from handler decision state.
+     * @param context - Current Step or RPC Context.
+     * @returns The decoded Attribute value.
+     */
     get(context) {
         return context.getAttribute(this);
     }
+    /**
+     * Stages a value to persist with the current decision.
+     * @param context - Current Step or RPC Context.
+     * @param value - Typed value to persist.
+     */
     set(context, value) {
         context.setAttribute(this, value);
     }
+    /**
+     * Stages deletion in the current decision.
+     * @param context - Current Step or RPC Context.
+     */
     delete(context) {
         context.deleteAttribute(this);
     }
+    /**
+     * Returns an immutable Attribute definition whose writes are projected to the Flow's Attribute Store.
+     *
+     * Projection is asynchronous and latest-state only. Deletion writes SQL `NULL`, projection failures do
+     * not roll back Flow Attribute writes, and the Flow must select a configured Attribute Store name.
+     * @returns A new synced definition; this definition remains unchanged.
+     */
+    syncToAttributeStore() {
+        return markAttributeStoreSynced(new Attribute(this.name, this.codec, this.index));
+    }
+    /**
+     * Creates a lock request for this Attribute.
+     * @returns A lock for this singleton Attribute.
+     */
     lock() {
         return { attribute: this };
     }
 }
+/**
+ * Defines a typed family of durable values keyed by map instance.
+ * @typeParam T - Value encoded for every map instance.
+ */
 export class AttributeMap {
     name;
     codec;
     index;
+    /**
+     * Creates an AttributeMap definition for a PersistenceSchema.
+     * @param name - Non-empty logical name unique within the Flow.
+     * @param codec - Value codec shared by every instance.
+     * @param index - Optional shared visibility search index.
+     */
     constructor(name, codec, index) {
         this.name = name;
         this.codec = codec;
         this.index = index;
         requireName(name);
     }
+    /**
+     * Reads one map instance from handler decision state.
+     * @param context - Current Step or RPC Context.
+     * @param instance - Non-empty logical map key.
+     * @returns The decoded instance value.
+     */
     get(context, instance) {
         return context.getAttribute(this, instance);
     }
+    /**
+     * Stages one map-instance write.
+     * @param context - Current Step or RPC Context.
+     * @param instance - Non-empty logical map key.
+     * @param value - Typed value to persist.
+     */
     set(context, instance, value) {
         context.setAttribute(this, value, instance);
     }
+    /**
+     * Stages deletion of one map instance.
+     * @param context - Current Step or RPC Context.
+     * @param instance - Non-empty logical map key.
+     */
     delete(context, instance) {
         context.deleteAttribute(this, instance);
     }
+    /**
+     * Returns the number of existing instances, including buffered writes.
+     * @param context - Current Step or RPC Context.
+     * @returns The number of keys visible after decision-local writes and deletions.
+     */
+    getMapSize(context) {
+        return this.getAllInstanceKeys(context).length;
+    }
+    /**
+     * Returns decoded existing instance keys in ascending order.
+     * @param context - Current Step or RPC Context.
+     * @returns Keys visible after decision-local writes and deletions.
+     */
+    getAllInstanceKeys(context) {
+        return context.attributeMapKeys(this);
+    }
+    /**
+     * Returns an immutable AttributeMap definition whose writes are projected to the Flow's Attribute Store.
+     *
+     * Projection is asynchronous and latest-state only. Each map instance uses its physical Attribute name.
+     * Deletion writes SQL `NULL`, projection failures do not roll back Flow Attribute writes, and the Flow
+     * must select a configured Attribute Store name.
+     * @returns A new synced definition; this definition remains unchanged.
+     */
+    syncToAttributeStore() {
+        return markAttributeStoreSynced(new AttributeMap(this.name, this.codec, this.index));
+    }
+    /**
+     * Creates a lock request scoped to one map instance.
+     * @param instance - Non-empty logical map key.
+     * @returns A lock for the requested instance.
+     */
     lock(instance) {
         requireName(instance);
         return { attribute: this, instance };

package/dist/src/persistence.js.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/persistence.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,uDAAuD;AACvD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,wDAAwD;AAKxD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;IACrC,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,UAAU;IACrB,aAAa,EAAE,cAAc;IAC7B,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;CACZ,CAAC,CAAC;AAcZ,MAAM,OAAO,SAAS;IAEF;IACA;IACA;IAHlB,YACkB,IAAY,EACZ,KAAe,EACf,KAAsB;QAFtB,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAU;QACf,UAAK,GAAL,KAAK,CAAiB;QAEtC,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IAEM,GAAG,CAAC,OAAgB;QACzB,OAAO,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAEM,GAAG,CAAC,OAAgB,EAAE,KAAQ;QACnC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAEM,MAAM,CAAC,OAAgB;QAC5B,OAAO,CAAC,eAAe,CAAC,IAA0B,CAAC,CAAC;IACtD,CAAC;IAEM,IAAI;QACT,OAAO,EAAE,SAAS,EAAE,IAA0B,EAAE,CAAC;IACnD,CAAC;CACF;AAED,MAAM,OAAO,YAAY;IAEL;IACA;IACA;IAHlB,YACkB,IAAY,EACZ,KAAe,EACf,KAAsB;QAFtB,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAU;QACf,UAAK,GAAL,KAAK,CAAiB;QAEtC,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IAEM,GAAG,CAAC,OAAgB,EAAE,QAAgB;QAC3C,OAAO,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAEM,GAAG,CAAC,OAAgB,EAAE,QAAgB,EAAE,KAAQ;QACrD,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAEM,MAAM,CAAC,OAAgB,EAAE,QAAgB;QAC9C,OAAO,CAAC,eAAe,CAAC,IAA6B,EAAE,QAAQ,CAAC,CAAC;IACnE,CAAC;IAEM,IAAI,CAAC,QAAgB;QAC1B,WAAW,CAAC,QAAQ,CAAC,CAAC;QACtB,OAAO,EAAE,SAAS,EAAE,IAA6B,EAAE,QAAQ,EAAE,CAAC;IAChE,CAAC;CACF"}
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/persistence.ts"],"names":[],"mappings":"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"}

package/dist/src/rpc.d.ts

@@ -3,16 +3,37 @@ import type { Context } from "./context.js";
 import type { Flow } from "./flow.js";
 import type { AttributeLock } from "./persistence.js";
 import type { StepMovement } from "./step.js";
+/**
+ * Contains a typed RPC output and optional next-Step movements.
+ * @typeParam Output - Value decoded for the Client caller.
+ */
 export interface RPCResult<Output> {
+    /** Typed application result. */
     readonly output: Output;
+    /** Step movements applied atomically with handler persistence writes. */
     readonly nextSteps?: readonly StepMovement<unknown>[];
 }
+/**
+ * Describes a typed, possibly asynchronous RPC handler.
+ * @typeParam Input - Handler input type.
+ * @typeParam Output - Handler output type.
+ */
 export type RPC<Input, Output> = (context: Context, input: Input) => RPCResult<Output> | Promise<RPCResult<Output>>;
+/**
+ * Configures an RPC decorator's name, codecs, timeout, and Attribute locks.
+ * @typeParam Input - Handler input type.
+ * @typeParam Output - Handler output type.
+ */
 export interface RPCOptions<Input = unknown, Output = unknown> {
+    /** Protocol RPC name; uses the decorated method name when omitted. */
     readonly name?: string;
+    /** Required input codec for handlers that accept an input. */
     readonly inputCodec?: Codec<Input>;
+    /** Required output codec for handlers returning RPCResult. */
     readonly outputCodec?: Codec<Output>;
+    /** Non-negative handler timeout in milliseconds. */
     readonly timeoutMs?: number;
+    /** Attribute locks held for the entire invocation. */
     readonly lockAttributes?: readonly AttributeLock[];
 }
 export interface RegisteredRPC {
@@ -20,20 +41,52 @@ export interface RegisteredRPC {
     readonly name: string;
     readonly options: RPCOptions<any, any>;
 }
+/**
+ * Decorates an RPC with both typed input and output.
+ * @typeParam Input - Handler input type.
+ * @typeParam Output - Handler output type.
+ * @param options - Required input/output codecs and optional RPC settings.
+ * @returns A stage-3 method decorator validated during Registry construction.
+ */
 export declare function rpc<Input, Output>(options: RPCOptions<Input, Output> & {
+    /** Required codec for the handler input. */
     readonly inputCodec: Codec<Input>;
+    /** Required codec for the RPCResult output. */
     readonly outputCodec: Codec<Output>;
 }): <This>(method: (this: This, context: Context, input: Input) => RPCResult<Output> | Promise<RPCResult<Output>>, context: ClassMethodDecoratorContext<This, (this: This, context: Context, input: Input) => RPCResult<Output> | Promise<RPCResult<Output>>>) => void;
+/**
+ * Decorates an input-free RPC with typed output.
+ * @typeParam Output - Handler output type.
+ * @param options - Required output codec and optional RPC settings.
+ * @returns A stage-3 method decorator validated during Registry construction.
+ */
 export declare function rpc<Output>(options: RPCOptions<never, Output> & {
+    /** Input codecs are forbidden for an input-free handler. */
     readonly inputCodec?: never;
+    /** Required codec for the RPCResult output. */
     readonly outputCodec: Codec<Output>;
 }): <This>(method: (this: This, context: Context) => RPCResult<Output> | Promise<RPCResult<Output>>, context: ClassMethodDecoratorContext<This, (this: This, context: Context) => RPCResult<Output> | Promise<RPCResult<Output>>>) => void;
+/**
+ * Decorates a typed-input RPC with no output.
+ * @typeParam Input - Handler input type.
+ * @param options - Required input codec and optional RPC settings.
+ * @returns A stage-3 method decorator validated during Registry construction.
+ */
 export declare function rpc<Input>(options: RPCOptions<Input, never> & {
+    /** Required codec for the handler input. */
     readonly inputCodec: Codec<Input>;
+    /** Output codecs are forbidden for a void handler. */
     readonly outputCodec?: never;
 }): <This>(method: (this: This, context: Context, input: Input) => void | Promise<void>, context: ClassMethodDecoratorContext<This, (this: This, context: Context, input: Input) => void | Promise<void>>) => void;
+/**
+ * Decorates an input-free, output-free RPC.
+ * @param options - Optional name, timeout, and Attribute locks.
+ * @returns A stage-3 method decorator validated during Registry construction.
+ */
 export declare function rpc(options?: RPCOptions<never, never> & {
+    /** Input codecs are forbidden for an input-free handler. */
     readonly inputCodec?: never;
+    /** Output codecs are forbidden for a void handler. */
     readonly outputCodec?: never;
 }): <This>(method: (this: This, context: Context) => void | Promise<void>, context: ClassMethodDecoratorContext<This, (this: This, context: Context) => void | Promise<void>>) => void;
 export declare function registeredRPCs(flow: Flow<unknown>): readonly RegisteredRPC[];

package/dist/src/rpc.js

@@ -7,6 +7,23 @@
 // SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
 import { requireName } from "./validation.js";
 const rpcOptions = new WeakMap();
+/**
+ * Creates a typed RPC method decorator.
+ *
+ * Registry construction validates handler shape, codecs, unique names, and locks.
+ * The handler receives Context and optional input, then returns RPCResult or void.
+ *
+ * @example
+ * ```ts
+ * @rpc({ inputCodec: stringCodec, outputCodec: booleanCodec, timeoutMs: 10_000 })
+ * async cancel(context: Context, reason: string): Promise<RPCResult<boolean>> {
+ *   return { output: true };
+ * }
+ * ```
+ * @param options - Codecs and optional name, timeout, and lock settings.
+ * @returns A stage-3 method decorator.
+ * @throws {@link RangeError} when `timeoutMs` is negative.
+ */
 export function rpc(options = {}) {
     if (options.name !== undefined) {
         requireName(options.name);

package/dist/src/rpc.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/rpc.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,uDAAuD;AACvD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,wDAAwD;AAOxD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA0B9C,MAAM,UAAU,GAAG,IAAI,OAAO,EAAkC,CAAC;AAmDjE,MAAM,UAAU,GAAG,CAAC,UAAgC,EAAE;IACpD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,UAAU,CAAC,kCAAkC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvD,OAAO,UACL,MAAc,EACd,QAAmD;QAEnD,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAmB;IAChD,MAAM,UAAU,GAAoB,EAAE,CAAC;IACvC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,IAAI,SAAS,GAAkB,MAAM,CAAC,cAAc,CAAC,IAAI,CAAkB,CAAC;IAC5E,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QAC5D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;YACzD,IAAI,IAAI,KAAK,aAAa,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrD,SAAS;YACX,CAAC;YACD,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvB,MAAM,MAAM,GAAG,MAAM,CAAC,wBAAwB,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,KAAgB,CAAC;YAClF,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;gBACjC,SAAS;YACX,CAAC;YACD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,SAAS;YACX,CAAC;YACD,UAAU,CAAC,IAAI,CAAC;gBACd,MAAM;gBACN,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;gBAC1B,OAAO;aACR,CAAC,CAAC;QACL,CAAC;QACD,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,CAAkB,CAAC;IAChE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/rpc.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,uDAAuD;AACvD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,wDAAwD;AAOxD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA+C9C,MAAM,UAAU,GAAG,IAAI,OAAO,EAAkC,CAAC;AAmFjE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,GAAG,CAAC,UAAgC,EAAE;IACpD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,UAAU,CAAC,kCAAkC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvD,OAAO,UACL,MAAc,EACd,QAAmD;QAEnD,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAmB;IAChD,MAAM,UAAU,GAAoB,EAAE,CAAC;IACvC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,IAAI,SAAS,GAAkB,MAAM,CAAC,cAAc,CAAC,IAAI,CAAkB,CAAC;IAC5E,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QAC5D,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;YACzD,IAAI,IAAI,KAAK,aAAa,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrD,SAAS;YACX,CAAC;YACD,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvB,MAAM,MAAM,GAAG,MAAM,CAAC,wBAAwB,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,KAAgB,CAAC;YAClF,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;gBACjC,SAAS;YACX,CAAC;YACD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,SAAS;YACX,CAAC;YACD,UAAU,CAAC,IAAI,CAAC;gBACd,MAAM;gBACN,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;gBAC1B,OAAO;aACR,CAAC,CAAC;QACL,CAAC;QACD,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,CAAkB,CAAC;IAChE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}