Variable PersistListConst

Type declaration

• • new <EntityName extends string = string>(
        entityName: EntityName,
        baseDir?: string,
    ): {
        baseDir: string;
        entityName: EntityName;
        "[asyncIterator]"(): AsyncIterableIterator<any>;
        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

    • entityName: EntityName
    • OptionalbaseDir: string

    Returns {
        baseDir: string;
        entityName: EntityName;
        "[asyncIterator]"(): AsyncIterableIterator<any>;
        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>;
    }

    • ReadonlybaseDir: string

    • ReadonlyentityName: EntityName

    • [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>

        An async iterator yielding entities.

    • 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

          A function to test each entity, returning true to include it.

        Returns AsyncGenerator<T>

        An async generator yielding filtered entities in sorted order.

        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>

        A promise resolving to the count of stored entities.

        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

          The identifier of the entity to check (string or number), unique within its storage context.

        Returns Promise<boolean>

        A promise resolving to true if the entity exists, false otherwise.

        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>

        An async generator yielding each entity ID as a string or number.

        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>

        A promise resolving to the removed entity or null if the list is empty.

        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

          The entity to append to the list (e.g., a state update).

        Returns Promise<void>

        A promise that resolves when the entity is written to storage.

        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

          The identifier of the entity to read (string or number), unique within its storage context.

        Returns Promise<T>

        A promise resolving to the parsed entity data.

        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>

        A promise that resolves when all entities are removed.

        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

          The identifier of the entity to remove (string or number), unique within its storage context.

        Returns Promise<void>

        A promise that resolves when the entity is deleted.

        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

          The maximum number of entities to yield.
        • Optionalpredicate: (value: T) => boolean

          Optional function to filter entities before counting.

        Returns AsyncGenerator<T>

        An async generator yielding up to total entities in sorted order.

        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>

        An async generator yielding each entity in sorted order.

        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

          Indicates if this is the initial setup; reserved for future caching or optimization logic.

        Returns Promise<void>

        A promise that resolves when initialization is complete.

        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

          The identifier for the entity (string or number), unique within its storage context.
        • entity: T

          The entity data to persist (e.g., { agentName: "agent1" }).

        Returns Promise<void>

        A promise that resolves when the write operation is complete.

        Throws

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