Variable PersistBaseConst

PersistBase: 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>;
    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>;
}

Base class for persistent storage of entities in the swarm system, using the file system. Provides foundational methods for reading, writing, and managing entities as JSON files, supporting swarm utilities like PersistAliveUtils.

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>;
          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, SessionId), 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>;
          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).

      • 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).

Implements

Settings

Member Visibility