import { Ctx, ReadSignal } from "@kontsedal/olas-core";

//#region src/index.d.ts
type StorageAdapter = {
  get(key: string): string | null | Promise<string | null>;
  set(key: string, value: string): void | Promise<void>;
  delete(key: string): void | Promise<void>;
  onChange?(handler: (key: string, value: string | null) => void): () => void;
  /**
   * Optional — list every key currently in storage. Consumers that need to
   * enumerate keys (e.g. `@kontsedal/olas-mutation-queue` replaying the
   * pending queue on init) require this extension; consumers that only
   * `get` / `set` known keys (the typical `usePersisted` shape) don't need
   * it. Both built-in adapters (`localStorageAdapter`, `indexedDbAdapter`)
   * implement it.
   */
  keys?(): Iterable<string> | Promise<Iterable<string>>;
};
/**
 * Where a `PersistOptions.onError` fired. Distinguishes the failing operation
 * for routing (e.g. quota-exceeded vs schema-migration-failed vs
 * deserialization-corrupted).
 */
type PersistErrorOp = 'load' | 'deserialize' | 'serialize' | 'write' | 'migrate' | 'remoteChange';
type PersistOptions<T> = {
  /**
   * Storage backend. When omitted *or explicitly `undefined`* (handy for app
   * code that forwards a deps slot like `ctx.deps.storage`), the browser
   * `localStorageAdapter` is used. SSR-safe — `localStorageAdapter` no-ops
   * when `localStorage` isn't defined.
   */
  storage?: StorageAdapter | undefined;
  serialize?: (value: T) => string;
  deserialize?: (raw: string) => T;
  crossTab?: boolean;
  /**
   * Schema version. When the value loaded from storage carries a different
   * `version`, `migrate(raw, fromVersion)` is invoked to bring it forward;
   * the migrated value is written back atomically. When omitted, no version
   * gate runs — payloads are read and written raw (current default).
   *
   * The on-disk shape with versioning enabled is `{"v": N, "d": <serialized>}`
   * — `usePersisted` wraps every write and reads both shapes (legacy raw and
   * versioned). Versioned writes only happen once `version` is set.
   */
  version?: number;
  /**
   * Migrate a raw payload of a prior version. Receives the pre-deserialize
   * string and the version number it was written with (or `undefined` if no
   * version stamp existed, i.e. the legacy raw shape). Return the migrated
   * payload AS A `T` value (post-deserialize); `usePersisted` re-serializes
   * it before writing. Return `undefined` to drop the entry (the source
   * keeps its current value).
   */
  migrate?: (raw: string, fromVersion: number | undefined) => T | undefined | Promise<T | undefined>;
  /**
   * Debounce writes by `throttleMs` milliseconds. Useful for high-frequency
   * sources (cursor position, scroll, every-keystroke field) where the
   * default "write on every change" is too chatty. Defaults to `0` (no
   * debounce). On `ctx.onDispose`, any pending write is flushed.
   */
  throttleMs?: number;
  /**
   * Routed errors from every fallible op: storage `get`/`set` (quota,
   * security, version-conflict), `deserialize`/`serialize` (corrupt JSON,
   * non-serializable T), `migrate` (user-thrown), and `onChange` callbacks
   * (cross-tab payload corruption). Without this, errors are swallowed —
   * matches the historical behavior, but production apps want at least a
   * sentry/console hook.
   */
  onError?: (err: unknown, op: PersistErrorOp, key: string) => void;
};
type Persisted = {
  ready: ReadSignal<boolean>;
};
type PersistableSource<T> = {
  readonly value: T;
  set(value: T): void;
  subscribe(handler: (value: T) => void): () => void;
};
/**
 * Configuration for `indexedDbAdapter`. All fields optional; sane defaults
 * picked for typical app use.
 */
type IndexedDbAdapterOptions = {
  /** Database name. Defaults to `'olas-persist'`. */databaseName?: string; /** Object store inside the database. Defaults to `'kv'`. */
  storeName?: string;
  /**
   * `BroadcastChannel` name used to notify other tabs of writes through this
   * adapter (so `onChange` works cross-tab — IDB itself has no built-in
   * change event). Defaults to `'olas-persist:' + databaseName + '/' +
   * storeName`. Set to `null` to disable cross-tab notifications.
   */
  channelName?: string | null;
  /**
   * Override the `IDBFactory` — defaults to `globalThis.indexedDB`. Useful
   * for testing (inject a fake) or runtimes that ship their own IDB
   * implementation. When undefined and no global `indexedDB`, the adapter
   * no-ops (SSR-safe).
   */
  indexedDB?: IDBFactory;
  /**
   * Override the `BroadcastChannel` constructor. Defaults to
   * `globalThis.BroadcastChannel`. When undefined and no global, `onChange`
   * subscriptions still register but never fire.
   */
  broadcastChannel?: typeof BroadcastChannel;
};
/**
 * IndexedDB-backed `StorageAdapter`. Async on every operation; cross-tab
 * change notifications layered via `BroadcastChannel` (IDB has no native
 * change event, so external IDB writes by code that doesn't go through
 * this adapter are *not* observed). When no `IDBFactory` is available
 * (SSR, restricted environments), every method resolves to a no-op.
 *
 * Storage is a single key/value object store inside a single database;
 * fine for the persisted-signal use case `usePersisted` is built around.
 * For larger or schema-shaped data, write a custom adapter against your
 * own IDB layout.
 */
declare function indexedDbAdapter(options?: IndexedDbAdapterOptions): StorageAdapter;
/** Default localStorage adapter — only viable in the browser. */
declare const localStorageAdapter: StorageAdapter;
/**
 * Persist a signal-like source under `key`. Loads the stored value on
 * construction (sync for localStorage, async for any storage that returns a
 * promise). Subsequent writes to the source are mirrored to storage.
 *
 * Cleanup (unsubscribe + cross-tab listener removal) is bound to `ctx`.
 */
declare function usePersisted<T>(ctx: Ctx, key: string, source: PersistableSource<T>, options?: PersistOptions<T>): Persisted;
/**
 * Clear every key under a `prefix` (default: clear all). Useful for "log out"
 * flows that want to drop persisted state without enumerating consumers.
 * Errors are routed through the optional `onError` (e.g. quota or security
 * exceptions on `delete`).
 */
declare function clearPersisted(storage?: StorageAdapter, prefix?: string, onError?: (err: unknown, key: string) => void): Promise<void>;
//#endregion
export { IndexedDbAdapterOptions, PersistErrorOp, PersistOptions, PersistableSource, Persisted, StorageAdapter, clearPersisted, indexedDbAdapter, localStorageAdapter, usePersisted };
//# sourceMappingURL=index.d.cts.map