Variable PersistListConst

PersistList: new <EntityName extends string = string>(
    entityName: EntityName,
    baseDir?: string,
) => {
    "[asyncIterator]"(): AsyncIterableIterator<any>;
    baseDir: string;
    entityName: EntityName;
    filter<T extends IEntity = IEntity>(
        predicate: (value: T) => boolean,
    ): AsyncGenerator<T>;
    getCount(): Promise<number>;
    hasValue(entityId: EntityId): Promise<boolean>;
    keys(): AsyncGenerator<EntityId>;
    pop<T extends IEntity = IEntity>(): Promise<T>;
    push<T extends IEntity = IEntity>(entity: T): Promise<void>;
    readValue<T extends IEntity = IEntity>(entityId: EntityId): Promise<T>;
    removeAll(): Promise<void>;
    removeValue(entityId: EntityId): Promise<void>;
    take<T extends IEntity = IEntity>(
        total: number,
        predicate?: (value: T) => boolean,
    ): AsyncGenerator<T>;
    values<T extends IEntity = IEntity>(): AsyncGenerator<T>;
    waitForInit(initial: boolean): Promise<void>;
    writeValue<T extends IEntity = IEntity>(
        entityId: EntityId,
        entity: T,
    ): Promise<void>;
}

Extends PersistBase to provide a persistent list structure with push/pop operations. Manages entities with numeric keys for ordered access, suitable for queues or logs in the swarm system.

Type declaration

    • new <EntityName extends string = string>(
          entityName: EntityName,
          baseDir?: string,
      ): {
          "[asyncIterator]"(): AsyncIterableIterator<any>;
          baseDir: string;
          entityName: EntityName;
          filter<T extends IEntity = IEntity>(
              predicate: (value: T) => boolean,
          ): AsyncGenerator<T>;
          getCount(): Promise<number>;
          hasValue(entityId: EntityId): Promise<boolean>;
          keys(): AsyncGenerator<EntityId>;
          pop<T extends IEntity = IEntity>(): Promise<T>;
          push<T extends IEntity = IEntity>(entity: T): Promise<void>;
          readValue<T extends IEntity = IEntity>(entityId: EntityId): Promise<T>;
          removeAll(): Promise<void>;
          removeValue(entityId: EntityId): Promise<void>;
          take<T extends IEntity = IEntity>(
              total: number,
              predicate?: (value: T) => boolean,
          ): AsyncGenerator<T>;
          values<T extends IEntity = IEntity>(): AsyncGenerator<T>;
          waitForInit(initial: boolean): Promise<void>;
          writeValue<T extends IEntity = IEntity>(
              entityId: EntityId,
              entity: T,
          ): Promise<void>;
      }

    • Type Parameters

      • EntityName extends string = string

        The type of entity name (e.g., SwarmName), defaults to string, used as a subdirectory.

      Parameters

      Returns {
          "[asyncIterator]"(): AsyncIterableIterator<any>;
          baseDir: string;
          entityName: EntityName;
          filter<T extends IEntity = IEntity>(
              predicate: (value: T) => boolean,
          ): AsyncGenerator<T>;
          getCount(): Promise<number>;
          hasValue(entityId: EntityId): Promise<boolean>;
          keys(): AsyncGenerator<EntityId>;
          pop<T extends IEntity = IEntity>(): Promise<T>;
          push<T extends IEntity = IEntity>(entity: T): Promise<void>;
          readValue<T extends IEntity = IEntity>(entityId: EntityId): Promise<T>;
          removeAll(): Promise<void>;
          removeValue(entityId: EntityId): Promise<void>;
          take<T extends IEntity = IEntity>(
              total: number,
              predicate?: (value: T) => boolean,
          ): AsyncGenerator<T>;
          values<T extends IEntity = IEntity>(): AsyncGenerator<T>;
          waitForInit(initial: boolean): Promise<void>;
          writeValue<T extends IEntity = IEntity>(
              entityId: EntityId,
              entity: T,
          ): Promise<void>;
      }

      • [asyncIterator]:function
        • "[asyncIterator]"(): AsyncIterableIterator<any>

          Implements the async iterator protocol for iterating over entities. Delegates to the values method for iteration, enabling for await loops over entities.

          Returns AsyncIterableIterator<any>

      • ReadonlybaseDir: string
      • ReadonlyentityName: EntityName
      • filter:function
        • filter<T extends IEntity = IEntity>(
              predicate: (value: T) => boolean,
          ): AsyncGenerator<T>

          Filters entities based on a predicate function, yielding only matching entities. Useful for selective retrieval (e.g., finding online SessionIds in a SwarmName).

          Type Parameters

          • T extends IEntity = IEntity

            The specific type of the entities (e.g., IPersistAliveData), defaults to IEntity.

          Parameters

          • predicate: (value: T) => boolean

          Returns AsyncGenerator<T>

          Throws

          If reading entities fails during iteration (e.g., invalid JSON).

      • getCount:function
        • getCount(): Promise<number>

          Retrieves the number of entities stored in the directory. Counts only files with a .json extension, useful for monitoring storage usage (e.g., active sessions).

          Returns Promise<number>

          Throws

          If reading the directory fails (e.g., permissions or directory not found).

      • hasValue:function
        • hasValue(entityId: EntityId): Promise<boolean>

          Checks if an entity exists in storage by its ID. Efficiently verifies presence without reading the full entity (e.g., checking if a SessionId has memory).

          Parameters

          • entityId: EntityId

          Returns Promise<boolean>

          Throws

          If checking existence fails for reasons other than the file not existing.

      • keys:function
        • keys(): AsyncGenerator<EntityId>

          Iterates over all entity IDs in storage, sorted numerically. Yields IDs in ascending order, useful for key enumeration (e.g., listing SessionIds in a SwarmName).

          Returns AsyncGenerator<EntityId>

          Throws

          If reading the directory fails (e.g., permissions or directory not found).

      • pop:function
        • pop<T extends IEntity = IEntity>(): Promise<T>

          Removes and returns the last entity from the persistent list. Useful for dequeuing items or retrieving recent entries (e.g., latest event in a SwarmName log).

          Type Parameters

          • T extends IEntity = IEntity

            The specific type of the entity (e.g., IPersistStateData), defaults to IEntity.

          Returns Promise<T>

          Throws

          If reading or removing the entity fails (e.g., file not found).

      • push:function
        • push<T extends IEntity = IEntity>(entity: T): Promise<void>

          Adds an entity to the end of the persistent list with a new unique numeric key. Useful for appending items like messages or events in swarm operations (e.g., within a SwarmName).

          Type Parameters

          • T extends IEntity = IEntity

            The specific type of the entity (e.g., IPersistStateData), defaults to IEntity.

          Parameters

          • entity: T

          Returns Promise<void>

          Throws

          If writing to the file system fails (e.g., permissions or disk space).

      • readValue:function
        • readValue<T extends IEntity = IEntity>(entityId: EntityId): Promise<T>

          Reads an entity from storage by its ID, parsing it from a JSON file. Core method for retrieving persisted data (e.g., alive status for a SessionId in a SwarmName context).

          Type Parameters

          • T extends IEntity = IEntity

            The specific type of the entity (e.g., IPersistAliveData), defaults to IEntity.

          Parameters

          • entityId: EntityId

          Returns Promise<T>

          Throws

          If the file is not found (ENOENT) or parsing fails (e.g., invalid JSON).

      • removeAll:function
        • removeAll(): Promise<void>

          Removes all entities from storage under this entity name. Deletes all .json files in the directory, useful for resetting persistence (e.g., clearing a SwarmName’s data).

          Returns Promise<void>

          Throws

          If reading the directory or deleting files fails (e.g., permissions).

      • removeValue:function
        • removeValue(entityId: EntityId): Promise<void>

          Removes an entity from storage by its ID. Deletes the corresponding JSON file, used for cleanup (e.g., removing a SessionId’s memory).

          Parameters

          • entityId: EntityId

          Returns Promise<void>

          Throws

          If the entity is not found (ENOENT) or deletion fails (e.g., permissions).

      • take:function
        • take<T extends IEntity = IEntity>(
              total: number,
              predicate?: (value: T) => boolean,
          ): AsyncGenerator<T>

          Takes a limited number of entities, optionally filtered by a predicate. Stops yielding after reaching the specified total, useful for pagination (e.g., sampling SessionIds).

          Type Parameters

          • T extends IEntity = IEntity

            The specific type of the entities (e.g., IPersistStateData), defaults to IEntity.

          Parameters

          • total: number
          • Optionalpredicate: (value: T) => boolean

          Returns AsyncGenerator<T>

          Throws

          If reading entities fails during iteration (e.g., permissions).

      • values:function
        • values<T extends IEntity = IEntity>(): AsyncGenerator<T>

          Iterates over all entities in storage, sorted numerically by ID. Yields entities in ascending order, useful for batch processing (e.g., listing all SessionIds in a SwarmName).

          Type Parameters

          • T extends IEntity = IEntity

            The specific type of the entities (e.g., IPersistAliveData), defaults to IEntity.

          Returns AsyncGenerator<T>

          Throws

          If reading the directory or entity files fails (e.g., permissions or invalid JSON).

      • waitForInit:function
        • waitForInit(initial: boolean): Promise<void>

          Initializes the storage directory, creating it if it doesn’t exist, and validates existing entities. Removes invalid JSON files during initialization to ensure data integrity (e.g., for SwarmName-based alive status).

          Parameters

          • initial: boolean

          Returns Promise<void>

          Throws

          If directory creation or entity validation fails (e.g., permissions or I/O errors).

      • writeValue:function
        • writeValue<T extends IEntity = IEntity>(
              entityId: EntityId,
              entity: T,
          ): Promise<void>

          Writes an entity to storage with the specified ID, serializing it to JSON. Uses atomic file writing via writeFileAtomic to ensure data integrity (e.g., persisting AgentName for a SwarmName).

          Type Parameters

          • T extends IEntity = IEntity

            The specific type of the entity (e.g., IPersistActiveAgentData), defaults to IEntity.

          Parameters

          • entityId: EntityId
          • entity: T

          Returns Promise<void>

          Throws

          If writing to the file system fails (e.g., permissions or disk space).

Settings

Member Visibility