Class AttributeMap<T>

constructor

• new AttributeMap<T>(
      name: string,
      codec: Codec<T>,
      index?: AttributeIndex,
  ): AttributeMap<T>

  Creates an AttributeMap definition for a PersistenceSchema.

  Type Parameters

  • T

  Parameters

  • name: string

    Non-empty logical name without /, unique within the Flow.

  • codec: Codec<T>

    Value codec shared by every instance.

  • Optionalindex: AttributeIndex

    Optional shared visibility search index.

  Returns AttributeMap<T>

Readonlycodec

Optional Readonlyindex

Readonlyname

delete

• delete(context: Context, instance: string): void

  Stages deletion of one map instance.

  Parameters

  • context: Context

    Current Step or RPC Context.

  • instance: string

    The map instance. Slash is prohibited because it is a reserved character.

  Returns void

get

• get(context: Context, instance: string): T

  Reads one map instance from handler decision state.

  Parameters

  • context: Context

    Current Step or RPC Context.

  • instance: string

    The map instance. Slash is prohibited because it is a reserved character.

  Returns T

  The decoded instance value.

getAllInstanceKeys

• getAllInstanceKeys(context: Context): readonly string[]

  Returns decoded existing instance keys in ascending order.

  Parameters

  • context: Context

    Current Step or RPC Context.

  Returns readonly string[]

  Keys visible after decision-local writes and deletions.

getMapSize

• getMapSize(context: Context): number

  Returns the number of existing instances, including buffered writes.

  Parameters

  • context: Context

    Current Step or RPC Context.

  Returns number

  The number of keys visible after decision-local writes and deletions.

hardDeleteOnNull

• hardDeleteOnNull(): AttributeMap<T>

  Returns an immutable AttributeMap definition for short-lived secrets that Dex can permanently delete.

  Use this option for per-instance values such as API keys or access tokens that must not remain in Flow history. Dex stores each instance value only in the Dex blob store, never in Flow history. Deleting an instance or setting it to null or undefined permanently deletes its stored value. Register the returned definition in the Flow's PersistenceSchema. Use that same definition for handler reads and writes, InitialAttribute values, and SubFlow initial Attributes.

  Only string and object values are supported. Object values include JSON values and byte arrays. Numeric and Boolean values are rejected. A built-in numeric or Boolean codec fails here. A custom codec that encodes a number or Boolean fails when the value is written. Deletion is always allowed. A hard-delete AttributeMap cannot have an index and cannot use AttributeMap.syncToAttributeStore. Client.waitForAttributeMatch rejects a hard-delete AttributeMap before contacting Dex.

  Writes require a Dex Server with an enabled blob store and Server protocol version 3 or later. Otherwise, the write fails. The Client checks the Server protocol version once before its first hard-delete write. The Worker checks it at startup and fails any handler result that writes a hard-delete AttributeMap instance to an older Server. Step and RPC handlers receive instance values inline. The SDK never stores them in the local blob cache.

  Limitations:

  • Each Flow keeps one stored copy per map instance and overwrites it in place.
  • A Step or RPC attempt writes or deletes the stored value before Dex commits its result. A retried attempt, other Steps and RPCs, and Client reads can therefore observe a write or deletion from an attempt that later failed.
  • When concurrent Steps or RPCs write the same instance, the final stored value may not be the value of the last committed write.
  • A failed startFlow or SubFlow start for a Flow ID that is already running still overwrites the running Flow's stored value. A null initial value deletes it.
  • Executions that reuse a Flow ID share the stored values.
  • Client.timeTravel does not restore a deleted value. A deleted instance reads as absent.
  • A Flow retry or a restarted SubFlow starts from the original initial value. If an earlier run deleted that value, the new run reads it as absent.
  • Removing AttributeMap.hardDeleteOnNull from a definition leaves the stored value in place until Dex removes the Flow. Delete the value with the hard-delete definition first.
  • Values remain until they are deleted, or until Dex removes the Flow through retention and blob cleanup.
  • Blob store backups or bucket versioning can retain copies outside Dex's control.

  Returns AttributeMap<T>

  A new hard-delete definition; this definition remains unchanged.

  Example

  type VendorToken = { readonly token: string };
  const vendorTokens = new AttributeMap("vendor-tokens", jsonCodec<VendorToken>())
    .hardDeleteOnNull();
  
  class RevokeTokenStep implements Step<string> {
    public readonly inputCodec = stringCodec;
  
    public getStepType(): string {
      return "RevokeTokenStep";
    }
  
    public getStepOptions(): StepOptions {
      return { executeLoadAttributeMapInstances: [vendorTokens.load("billing")] };
    }
  
    public async execute(context: Context, revokeUrl: string): Promise<StepDecision> {
      const { token } = vendorTokens.get(context, "billing");
      await fetch(revokeUrl, { method: "POST", body: token });
      vendorTokens.delete(context, "billing");
      return gracefulComplete("revoked");
    }
  }
  
  class TokenRevocationFlow implements Flow<string> {
    private readonly revokeToken = new RevokeTokenStep();
  
    public getFlowType(): string {
      return "TokenRevocationFlow";
    }
  
    public getSteps() {
      return StepList.startStep(this.revokeToken);
    }
  
    public getPersistenceSchema(): PersistenceSchema {
      return { attributes: [vendorTokens] };
    }
  }
  
  const flow = new TokenRevocationFlow();
  const client = new Client(new Registry([flow]), cache);
  await client.startFlow(flow, "revoke-42", "https://vendor.example/revoke", {
    attributes: [InitialAttribute.mapValue(vendorTokens, "billing", { token: "token-value" })],
  });
  Copy

  Throws

  When this definition has an index, uses Attribute Store synchronization, or uses a built-in numeric or Boolean codec.

instance

• instance(instance: string): AttributeMapInstance<T>

  Selects one instance of this AttributeMap for Client.getAttributes.

  Use the result as one read in a getAttributes call. The selection keeps this AttributeMap's value type, so the matching result element has type T | undefined. To load an instance into a Step, RPC, or timeout-handler snapshot, use AttributeMap.load.

  Parameters

  • instance: string

    Non-empty logical map key. Slash is prohibited because it is a reserved character. The SDK escapes the key for the protocol.

  Returns AttributeMapInstance<T>

  A new selection of this AttributeMap and instance. It does not contact Dex.

  Example

  type Note = { readonly text: string };
  const notes = new AttributeMap("notes", jsonCodec<Note>());
  const [note] = await client.getAttributes("order-42", notes.instance("n1"));
  const text = note?.text ?? "no note yet";
  Copy

  Throws

  When instance is empty, contains only whitespace, or contains /.

load

• load(instance: string): AttributeMapLoad

  Selects one logical instance for a handler snapshot.

  Parameters

  • instance: string

    Non-empty logical map key. The SDK escapes it for the protocol.

  Returns AttributeMapLoad

  An exact instance load for RPC, Step, or timeout-handler options.

lock

• lock(instance: string): AttributeLock

  Creates a lock request scoped to one map instance.

  Parameters

  • instance: string

    The map instance. Slash is prohibited because it is a reserved character.

  Returns AttributeLock

  A lock for the requested instance.

set

• set(context: Context, instance: string, value: T): void

  Stages one map-instance write.

  Parameters

  • context: Context

    Current Step or RPC Context.

  • instance: string

    The map instance. Slash is prohibited because it is a reserved character.

  • value: T

    Typed value to persist.

  Returns void

syncToAttributeStore

• syncToAttributeStore(): AttributeMap<T>

  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 AttributeMap<T>

  A new synced definition; this definition remains unchanged.

  Throws

  When this definition uses AttributeMap.hardDeleteOnNull.