Storage API Reference

/**
 * Base interface for key-value stores
 */
interface BaseStore<K = string, V = any> {
  /**
   * Get multiple values by keys
   */
  mget(keys: K[]): Promise<(V | undefined)[]>;

  /**
   * Set multiple key-value pairs
   */
  mset(keyValuePairs: [K, V][]): Promise<void>;

  /**
   * Delete multiple keys
   */
  mdelete(keys: K[]): Promise<void>;

  /**
   * Yield keys with optional prefix filter
   */
  yieldKeys(prefix?: string): AsyncGenerator<string>;
}

/**
 * In-memory key-value store
 */
class InMemoryStore<V = any> {
  /**
   * Get multiple values by keys
   */
  mget(keys: string[]): Promise<(V | undefined)[]>;

  /**
   * Set multiple key-value pairs
   */
  mset(keyValuePairs: [string, V][]): Promise<void>;

  /**
   * Delete multiple keys
   */
  mdelete(keys: string[]): Promise<void>;

  /**
   * Yield keys with optional prefix filter
   */
  yieldKeys(prefix?: string): AsyncGenerator<string>;
}

/**
 * File system-based storage for key-value pairs
 */
class LocalFileStore {
  /**
   * Create LocalFileStore with root path
   * @param fields - Configuration with rootPath
   */
  constructor(fields: { rootPath: string });

  /**
   * Get a single parsed file by key
   * @param key - File key
   * @returns Promise resolving to Uint8Array or undefined
   */
  getParsedFile(key: string): Promise<Uint8Array | undefined>;

  /**
   * Get multiple values by keys
   */
  mget(keys: string[]): Promise<(Uint8Array | undefined)[]>;

  /**
   * Set multiple key-value pairs
   */
  mset(keyValuePairs: [string, Uint8Array][]): Promise<void>;

  /**
   * Delete multiple keys
   */
  mdelete(keys: string[]): Promise<void>;

  /**
   * Yield keys with optional prefix filter
   */
  yieldKeys(prefix?: string): AsyncGenerator<string>;

  /**
   * Initialize from file system path (convenience method)
   * @param rootPath - Root directory path
   * @returns Promise resolving to LocalFileStore instance
   */
  static fromPath(rootPath: string): Promise<LocalFileStore>;
}

/**
 * Store with encoding/decoding layer over base storage
 */
class EncoderBackedStore<K = string, V = any, SerializedType = Uint8Array> {
  /**
   * Get multiple values by keys
   */
  mget(keys: K[]): Promise<(V | undefined)[]>;

  /**
   * Set multiple key-value pairs
   */
  mset(keyValuePairs: [K, V][]): Promise<void>;

  /**
   * Delete multiple keys
   */
  mdelete(keys: K[]): Promise<void>;

  /**
   * Yield keys with optional prefix filter
   */
  yieldKeys(prefix?: string): AsyncGenerator<string>;

  /**
   * Create encoder-backed store
   */
  constructor(fields: {
    store: BaseStore<string, SerializedType>;
    keyEncoder: (key: K) => string;
    valueSerializer: (value: V) => SerializedType;
    valueDeserializer: (serialized: SerializedType) => V;
  });
}

/**
 * Create document store from byte store
 */
function createDocumentStoreFromByteStore(
  store: BaseStore<string, Uint8Array>
): EncoderBackedStore<string, Document, Uint8Array>;