.opencode/node_modules/effect/dist/unstable/persistence/KeyValueStore.d.ts

/**
 * Provides effectful key/value storage for persistence backends.
 *
 * `KeyValueStore` is a service for storing string or binary values by key. It
 * is useful for lightweight durable state, browser storage, local files, SQL
 * tables, tests, and as a storage building block for higher-level persistence
 * APIs. This module includes store operations, prefixed views, schema-aware JSON
 * storage, error values, and layers for memory, filesystem, Web Storage, and
 * SQL-backed stores.
 *
 * @since 4.0.0
 */
import * as Context from "../../Context.ts";
import * as Effect from "../../Effect.ts";
import * as FileSystem from "../../FileSystem.ts";
import { type LazyArg } from "../../Function.ts";
import * as Layer from "../../Layer.ts";
import * as Option from "../../Option.ts";
import * as Path from "../../Path.ts";
import type { PlatformError } from "../../PlatformError.ts";
import * as Schema from "../../Schema.ts";
import * as SqlClient from "../sql/SqlClient.ts";
declare const TypeId: "~effect/persistence/KeyValueStore";
/**
 * Effectful key/value store service for string and binary values.
 *
 * @category models
 * @since 4.0.0
 */
export interface KeyValueStore {
    readonly [TypeId]: typeof TypeId;
    /**
     * Returns the value of the specified key if it exists.
     */
    readonly get: (key: string) => Effect.Effect<string | undefined, KeyValueStoreError>;
    /**
     * Returns the value of the specified key if it exists.
     */
    readonly getUint8Array: (key: string) => Effect.Effect<Uint8Array | undefined, KeyValueStoreError>;
    /**
     * Sets the value of the specified key.
     */
    readonly set: (key: string, value: string | Uint8Array) => Effect.Effect<void, KeyValueStoreError>;
    /**
     * Removes the specified key.
     */
    readonly remove: (key: string) => Effect.Effect<void, KeyValueStoreError>;
    /**
     * Removes all entries.
     */
    readonly clear: Effect.Effect<void, KeyValueStoreError>;
    /**
     * Returns the number of entries.
     */
    readonly size: Effect.Effect<number, KeyValueStoreError>;
    /**
     * Updates the value of the specified key if it exists.
     */
    readonly modify: (key: string, f: (value: string) => string) => Effect.Effect<string | undefined, KeyValueStoreError>;
    /**
     * Updates the value of the specified key if it exists.
     */
    readonly modifyUint8Array: (key: string, f: (value: Uint8Array) => Uint8Array) => Effect.Effect<Uint8Array | undefined, KeyValueStoreError>;
    /**
     * Returns true if the KeyValueStore contains the specified key.
     */
    readonly has: (key: string) => Effect.Effect<boolean, KeyValueStoreError>;
    /**
     * Checks whether the KeyValueStore contains any entries.
     */
    readonly isEmpty: Effect.Effect<boolean, KeyValueStoreError>;
}
/**
 * Implementation callbacks used by `make` to construct a `KeyValueStore`.
 *
 * **Details**
 *
 * Primitive operations are required, while helpers such as `has`, `isEmpty`,
 * and `modify` can be supplied to override the defaults.
 *
 * @category options
 * @since 4.0.0
 */
export type MakeOptions = Partial<KeyValueStore> & {
    /**
     * Returns the value of the specified key if it exists.
     */
    readonly get: (key: string) => Effect.Effect<string | undefined, KeyValueStoreError>;
    /**
     * Returns the value of the specified key if it exists.
     */
    readonly getUint8Array: (key: string) => Effect.Effect<Uint8Array | undefined, KeyValueStoreError>;
    /**
     * Sets the value of the specified key.
     */
    readonly set: (key: string, value: string | Uint8Array) => Effect.Effect<void, KeyValueStoreError>;
    /**
     * Removes the specified key.
     */
    readonly remove: (key: string) => Effect.Effect<void, KeyValueStoreError>;
    /**
     * Removes all entries.
     */
    readonly clear: Effect.Effect<void, KeyValueStoreError>;
    /**
     * Returns the number of entries.
     */
    readonly size: Effect.Effect<number, KeyValueStoreError>;
};
/**
 * Implementation callbacks for adapting a string-only backing store into a
 * `KeyValueStore`.
 *
 * @category options
 * @since 4.0.0
 */
export type MakeStringOptions = Partial<Omit<KeyValueStore, "set">> & {
    /**
     * Returns the value of the specified key if it exists.
     */
    readonly get: (key: string) => Effect.Effect<string | undefined, KeyValueStoreError>;
    /**
     * Sets the value of the specified key.
     */
    readonly set: (key: string, value: string) => Effect.Effect<void, KeyValueStoreError>;
    /**
     * Removes the specified key.
     */
    readonly remove: (key: string) => Effect.Effect<void, KeyValueStoreError>;
    /**
     * Removes all entries.
     */
    readonly clear: Effect.Effect<void, KeyValueStoreError>;
    /**
     * Returns the number of entries.
     */
    readonly size: Effect.Effect<number, KeyValueStoreError>;
};
declare const ErrorTypeId: "~effect/persistence/KeyValueStore/KeyValueStoreError";
declare const KeyValueStoreError_base: new <A extends Record<string, any> = {}>(args: import("../../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../../Cause.ts").YieldableError & {
    readonly _tag: "KeyValueStoreError";
} & Readonly<A>;
/**
 * Error raised by key/value store operations, including the failed method,
 * optional key, message, and cause.
 *
 * @category errors
 * @since 4.0.0
 */
export declare class KeyValueStoreError extends KeyValueStoreError_base<{
    message: string;
    method: string;
    key?: string;
    cause?: unknown;
}> {
    /**
     * Marks this value as a key-value store error for runtime guards.
     *
     * @since 4.0.0
     */
    readonly [ErrorTypeId]: typeof ErrorTypeId;
}
/**
 * Service tag for string and binary key/value storage.
 *
 * **When to use**
 *
 * Use to access or provide the persistence store used for lightweight durable
 * state.
 *
 * @category services
 * @since 4.0.0
 */
export declare const KeyValueStore: Context.Service<KeyValueStore, KeyValueStore>;
/**
 * Constructs a `KeyValueStore` from primitive store operations.
 *
 * **Details**
 *
 * Default implementations are derived for `has`, `isEmpty`, `modify`, and
 * `modifyUint8Array` unless they are provided in the options.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const make: (options: MakeOptions) => KeyValueStore;
/**
 * Adapts a string-only backing store into a `KeyValueStore`.
 *
 * **Details**
 *
 * `Uint8Array` values are stored as base64 strings. `getUint8Array` decodes
 * base64 values and falls back to UTF-8 encoding for non-base64 strings.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const makeStringOnly: (options: MakeStringOptions) => KeyValueStore;
/**
 * Returns a view of a `KeyValueStore` that prepends the given prefix to every
 * key.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const prefix: {
    /**
     * Returns a view of a `KeyValueStore` that prepends the given prefix to every
     * key.
     *
     * @category combinators
     * @since 4.0.0
     */
    (prefix: string): (self: KeyValueStore) => KeyValueStore;
    /**
     * Returns a view of a `KeyValueStore` that prepends the given prefix to every
     * key.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: KeyValueStore, prefix: string): KeyValueStore;
};
/**
 * Provides a process-local in-memory `KeyValueStore` backed by a `Map`.
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerMemory: Layer.Layer<KeyValueStore>;
/**
 * Provides a `KeyValueStore` backed by files in the specified directory.
 *
 * **Details**
 *
 * The directory is created if needed, and each key is encoded as a file name.
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerFileSystem: (directory: string) => Layer.Layer<KeyValueStore, PlatformError, FileSystem.FileSystem | Path.Path>;
/**
 * Options for configuring the SQL-backed `KeyValueStore` layer.
 *
 * @category layers
 * @since 4.0.0
 */
export interface LayerSqlOptions {
    /**
     * The SQL table name used to store values.
     *
     * @default "effect_key_value_store"
     */
    readonly table?: string;
}
/**
 * Provides a SQL-backed `KeyValueStore`.
 *
 * **Details**
 *
 * The layer creates the configured table if it does not exist and stores both
 * string and binary values through the current `SqlClient`.
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerSql: (options?: LayerSqlOptions) => Layer.Layer<KeyValueStore, never, SqlClient.SqlClient>;
declare const SchemaStoreTypeId: "~effect/persistence/KeyValueStore/SchemaStore";
/**
 * Schema-aware view of a `KeyValueStore` that stores values as encoded JSON.
 *
 * @category SchemaStore
 * @since 4.0.0
 */
export interface SchemaStore<S extends Schema.Top> {
    readonly [SchemaStoreTypeId]: typeof SchemaStoreTypeId;
    /**
     * Returns the value of the specified key if it exists.
     */
    readonly get: (key: string) => Effect.Effect<Option.Option<S["Type"]>, KeyValueStoreError | Schema.SchemaError, S["DecodingServices"]>;
    /**
     * Sets the value of the specified key.
     */
    readonly set: (key: string, value: S["Type"]) => Effect.Effect<void, KeyValueStoreError | Schema.SchemaError, S["EncodingServices"]>;
    /**
     * Removes the specified key.
     */
    readonly remove: (key: string) => Effect.Effect<void, KeyValueStoreError>;
    /**
     * Removes all entries.
     */
    readonly clear: Effect.Effect<void, KeyValueStoreError>;
    /**
     * Returns the number of entries.
     */
    readonly size: Effect.Effect<number, KeyValueStoreError>;
    /**
     * Updates the value of the specified key if it exists.
     */
    readonly modify: (key: string, f: (value: S["Type"]) => S["Type"]) => Effect.Effect<Option.Option<S["Type"]>, KeyValueStoreError | Schema.SchemaError, S["DecodingServices"] | S["EncodingServices"]>;
    /**
     * Returns true if the KeyValueStore contains the specified key.
     */
    readonly has: (key: string) => Effect.Effect<boolean, KeyValueStoreError>;
    /**
     * Checks whether the KeyValueStore contains any entries.
     */
    readonly isEmpty: Effect.Effect<boolean, KeyValueStoreError>;
}
/**
 * Adapts a `KeyValueStore` into a `SchemaStore` using the schema's JSON codec.
 *
 * @category SchemaStore
 * @since 4.0.0
 */
export declare const toSchemaStore: <S extends Schema.Top>(self: KeyValueStore, schema: S) => SchemaStore<S>;
/**
 * Provides a `KeyValueStore` backed by a Web `Storage` instance such as
 * `localStorage` or `sessionStorage`.
 *
 * **Details**
 *
 * This layer uses the Web Storage API:
 * https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerStorage: (evaluate: LazyArg<Storage>) => Layer.Layer<KeyValueStore>;
export {};
//# sourceMappingURL=KeyValueStore.d.ts.map