effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/persistence/KeyValueStore.ts

@@ -1,4 +1,25 @@
 /**
+ * Effectful key/value storage for persistence backends.
+ *
+ * This module defines the `KeyValueStore` service used by the persistence
+ * package when a simple string or binary store is enough. It is useful for
+ * lightweight durable state, browser storage, local file-backed data, SQL
+ * tables, test stores, and as the storage primitive underneath higher-level
+ * persistence APIs.
+ *
+ * Values are stored as strings or `Uint8Array`s, and `toSchemaStore` adds a
+ * schema-aware JSON layer for typed values. Schema changes can make existing
+ * JSON fail to decode, and `prefix` should be used to separate namespaces when
+ * several logical stores share the same backend. This service does not provide
+ * native TTL support; higher-level persistence layers encode expiration
+ * metadata in stored values when they need TTLs.
+ *
+ * Backend behavior is intentionally small but not identical: Web Storage is
+ * string-only, `makeStringOnly` stores binary values as base64, filesystem
+ * keys become encoded file names, SQL stores value type metadata in a table,
+ * and the memory layer is process-local. Choose keys, prefixes, table names,
+ * and value formats with those backend constraints in mind.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -21,8 +42,10 @@ import type { SqlError } from "../sql/SqlError.ts"
 const TypeId = "~effect/persistence/KeyValueStore" as const
 
 /**
+ * Effectful key/value store service for string and binary values.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface KeyValueStore {
   readonly [TypeId]: typeof TypeId
@@ -84,8 +107,13 @@ export interface KeyValueStore {
 }
 
 /**
+ * Implementation callbacks used by `make` to construct a `KeyValueStore`.
+ *
+ * Primitive operations are required, while helpers such as `has`, `isEmpty`,
+ * and `modify` can be supplied to override the defaults.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type MakeOptions = Partial<KeyValueStore> & {
   /**
@@ -120,8 +148,11 @@ export type MakeOptions = Partial<KeyValueStore> & {
 }
 
 /**
+ * Implementation callbacks for adapting a string-only backing store into a
+ * `KeyValueStore`.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type MakeStringOptions = Partial<Omit<KeyValueStore, "set">> & {
   /**
@@ -153,8 +184,11 @@ export type MakeStringOptions = Partial<Omit<KeyValueStore, "set">> & {
 const ErrorTypeId = "~effect/persistence/KeyValueStore/KeyValueStoreError" as const
 
 /**
+ * Error raised by key/value store operations, including the failed method,
+ * optional key, message, and cause.
+ *
+ * @category errors
  * @since 4.0.0
- * @category Errors
  */
 export class KeyValueStoreError extends Data.TaggedError("KeyValueStoreError")<{
   message: string
@@ -163,14 +197,18 @@ export class KeyValueStoreError extends Data.TaggedError("KeyValueStoreError")<{
   cause?: unknown
 }> {
   /**
+   * Marks this value as a key-value store error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ErrorTypeId]: typeof ErrorTypeId = ErrorTypeId
 }
 
 /**
- * @since 4.0.0
+ * Context service tag for the `KeyValueStore` service.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export const KeyValueStore: Context.Service<
   KeyValueStore,
@@ -178,8 +216,13 @@ export const KeyValueStore: Context.Service<
 > = Context.Service("effect/persistence/KeyValueStore")
 
 /**
- * @since 4.0.0
+ * Constructs a `KeyValueStore` from primitive store operations.
+ *
+ * Default implementations are derived for `has`, `isEmpty`, `modify`, and
+ * `modifyUint8Array` unless they are provided in the options.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (options: MakeOptions): KeyValueStore =>
   KeyValueStore.of({
@@ -215,8 +258,13 @@ export const make = (options: MakeOptions): KeyValueStore =>
   })
 
 /**
- * @since 4.0.0
+ * Adapts a string-only backing store into a `KeyValueStore`.
+ *
+ * `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 const makeStringOnly = (
   options: MakeStringOptions
@@ -241,18 +289,27 @@ export const makeStringOnly = (
 }
 
 /**
- * @since 4.0.0
+ * Returns a view of a `KeyValueStore` that prepends the given prefix to every
+ * key.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const prefix: {
   /**
-   * @since 4.0.0
+   * 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
   /**
-   * @since 4.0.0
+   * 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
 } = dual(2, (self: KeyValueStore, prefix: string): KeyValueStore => ({
@@ -267,8 +324,10 @@ export const prefix: {
 }))
 
 /**
- * @since 4.0.0
+ * Provides a process-local in-memory `KeyValueStore` backed by a `Map`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerMemory: Layer.Layer<KeyValueStore> = Layer.sync(KeyValueStore)(() => {
   const store = new Map<string, string | Uint8Array>()
@@ -293,8 +352,12 @@ export const layerMemory: Layer.Layer<KeyValueStore> = Layer.sync(KeyValueStore)
 })
 
 /**
- * @since 4.0.0
+ * Provides a `KeyValueStore` backed by files in the specified directory.
+ *
+ * The directory is created if needed, and each key is encoded as a file name.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerFileSystem = (
   directory: string
@@ -394,8 +457,10 @@ export const layerFileSystem = (
   }))
 
 /**
- * @since 4.0.0
+ * Options for configuring the SQL-backed `KeyValueStore` layer.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export interface LayerSqlOptions {
   /**
@@ -407,8 +472,13 @@ export interface LayerSqlOptions {
 }
 
 /**
- * @since 4.0.0
+ * Provides a SQL-backed `KeyValueStore`.
+ *
+ * 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 const layerSql = (
   options: LayerSqlOptions = {}
@@ -617,8 +687,10 @@ export const layerSql = (
 const SchemaStoreTypeId = "~effect/persistence/KeyValueStore/SchemaStore" as const
 
 /**
- * @since 4.0.0
+ * 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
@@ -676,8 +748,10 @@ export interface SchemaStore<S extends Schema.Top> {
 }
 
 /**
- * @since 4.0.0
+ * Adapts a `KeyValueStore` into a `SchemaStore` using the schema's JSON codec.
+ *
  * @category SchemaStore
+ * @since 4.0.0
  */
 export const toSchemaStore = <S extends Schema.Top>(self: KeyValueStore, schema: S): SchemaStore<S> => {
   const serializer = Schema.toCodecJson(schema)
@@ -725,12 +799,13 @@ export const toSchemaStore = <S extends Schema.Top>(self: KeyValueStore, schema:
 }
 
 /**
- * Creates an KeyValueStorage from an instance of the `Storage` api.
+ * Provides a `KeyValueStore` backed by a Web `Storage` instance such as
+ * `localStorage` or `sessionStorage`.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerStorage = (
   evaluate: LazyArg<Storage>
@@ -741,51 +816,56 @@ export const layerStorage = (
       get: (key: string) =>
         Effect.try({
           try: () => storage.getItem(key) ?? undefined,
-          catch: () =>
+          catch: (cause) =>
             new KeyValueStoreError({
               key,
               method: "get",
-              message: `Unable to get item with key ${key}`
+              message: `Unable to get item with key ${key}`,
+              cause
             })
         }),
 
       set: (key: string, value: string) =>
         Effect.try({
           try: () => storage.setItem(key, value),
-          catch: () =>
+          catch: (cause) =>
             new KeyValueStoreError({
               key,
               method: "set",
-              message: `Unable to set item with key ${key}`
+              message: `Unable to set item with key ${key}`,
+              cause
             })
         }),
 
       remove: (key: string) =>
         Effect.try({
           try: () => storage.removeItem(key),
-          catch: () =>
+          catch: (cause) =>
             new KeyValueStoreError({
               key,
               method: "remove",
-              message: `Unable to remove item with key ${key}`
+              message: `Unable to remove item with key ${key}`,
+              cause
             })
         }),
 
       clear: Effect.try({
         try: () => storage.clear(),
-        catch: () =>
+        catch: (cause) =>
           new KeyValueStoreError({
             method: "clear",
-            message: `Unable to clear storage`
+            message: `Unable to clear storage`,
+            cause
           })
       }),
 
       size: Effect.try({
         try: () => storage.length,
-        catch: () =>
+        catch: (cause) =>
           new KeyValueStoreError({
             method: "size",
-            message: `Unable to get size`
+            message: `Unable to get size`,
+            cause
           })
       })
     })

package/src/unstable/persistence/Persistable.ts

@@ -1,4 +1,24 @@
 /**
+ * Defines the request-side contract used by the persistence layer.
+ *
+ * A `Persistable` request is a `PrimaryKey` value that carries the success and
+ * error schemas needed to encode and decode the stored `Exit` for that request.
+ * Persisted request resolvers and `PersistedCache` use this metadata to restore
+ * previous lookup results from a backing store before running the lookup again.
+ *
+ * Use `Class` for cacheable or durable requests whose results can safely be
+ * reused across fibers, processes, or restarts. The request primary key is the
+ * entry id inside a persistence store, so it should be stable, collision-free,
+ * and usually include a request-specific prefix. The `storeId` is configured on
+ * `Persistence` or `PersistedCache`; it selects the backing store namespace and
+ * is separate from the request primary key.
+ *
+ * Success and error schemas are encoded with the JSON codec, so persisted
+ * values must be representable by those schemas and any required schema services
+ * must be available where the store reads or writes entries. Changing a schema,
+ * primary-key format, or store id can make existing persisted values fail to
+ * decode or stop being found, so treat those changes as persistence migrations.
+ *
  * @since 4.0.0
  */
 import type * as Duration from "../../Duration.ts"
@@ -11,14 +31,20 @@ import type * as Types from "../../Types.ts"
 import type { PersistenceError } from "./Persistence.ts"
 
 /**
- * @since 4.0.0
+ * Property key used to attach success and error schemas to persistable
+ * requests.
+ *
  * @category Symbols
+ * @since 4.0.0
  */
 export const symbol = "~effect/persistence/Persistable" as const
 
 /**
+ * A primary-keyed request value whose success and error results can be
+ * serialized for persistence.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Persistable<A extends Schema.Top, E extends Schema.Top> extends PrimaryKey.PrimaryKey {
   readonly [symbol]: {
@@ -28,54 +54,72 @@ export interface Persistable<A extends Schema.Top, E extends Schema.Top> extends
 }
 
 /**
+ * Any persistable request regardless of its success and error schemas.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Any = Persistable<Schema.Top, Schema.Top>
 
 /**
+ * Extracts the success schema from a persistable request.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type SuccessSchema<A extends Any> = A["~effect/persistence/Persistable"]["success"]
 
 /**
+ * Extracts the success value type from a persistable request.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Success<A extends Any> = A["~effect/persistence/Persistable"]["success"]["Type"]
 
 /**
+ * Extracts the error schema from a persistable request.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type ErrorSchema<A extends Any> = A["~effect/persistence/Persistable"]["error"]
 
 /**
+ * Extracts the error value type from a persistable request.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Error<A extends Any> = A["~effect/persistence/Persistable"]["error"]["Type"]
 
 /**
+ * Services required to decode a persisted success or error value for the
+ * request.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type DecodingServices<A extends Any> =
   | A["~effect/persistence/Persistable"]["success"]["DecodingServices"]
   | A["~effect/persistence/Persistable"]["error"]["DecodingServices"]
 
 /**
+ * Services required to encode a success or error value for persistence.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type EncodingServices<A extends Any> =
   | A["~effect/persistence/Persistable"]["success"]["EncodingServices"]
   | A["~effect/persistence/Persistable"]["error"]["EncodingServices"]
 
 /**
+ * All schema services required to encode and decode a persistable request
+ * result.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Services<A extends Any> =
   | A["~effect/persistence/Persistable"]["success"]["DecodingServices"]
@@ -84,14 +128,22 @@ export type Services<A extends Any> =
   | A["~effect/persistence/Persistable"]["error"]["EncodingServices"]
 
 /**
+ * Computes the time to live for a persisted result from the result `Exit` and
+ * request value.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type TimeToLiveFn<K extends Any> = (exit: Exit.Exit<Success<K>, Error<K>>, request: K) => Duration.Input
 
 /**
+ * Creates request classes that implement `Persistable` and `Request.Request`.
+ *
+ * The generated class stores the supplied tag, derives its primary key from
+ * the payload, and carries schemas for persisted success and error exits.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const Class = <
   Config extends {
@@ -154,8 +206,11 @@ export const Class = <
 }
 
 /**
- * @since 4.0.0
+ * Returns the cached `Exit` schema for a persistable request's success and
+ * error schemas.
+ *
  * @category Accessors
+ * @since 4.0.0
  */
 export const exitSchema = <A extends Schema.Top, E extends Schema.Top>(
   self: Persistable<A, E>
@@ -170,8 +225,11 @@ export const exitSchema = <A extends Schema.Top, E extends Schema.Top>(
 const exitSchemaCache = new WeakMap<Persistable<any, any>, Schema.Exit<any, any, Schema.Defect>>()
 
 /**
- * @since 4.0.0
+ * Encodes an `Exit` for a persistable request using its success and error
+ * schemas.
+ *
  * @category Serialization
+ * @since 4.0.0
  */
 export const serializeExit = <A extends Schema.Top, E extends Schema.Top>(
   self: Persistable<A, E>,
@@ -182,8 +240,11 @@ export const serializeExit = <A extends Schema.Top, E extends Schema.Top>(
 }
 
 /**
- * @since 4.0.0
+ * Decodes a persisted value into an `Exit` for a persistable request using its
+ * success and error schemas.
+ *
  * @category Serialization
+ * @since 4.0.0
  */
 export const deserializeExit = <A extends Schema.Top, E extends Schema.Top>(
   self: Persistable<A, E>,

package/src/unstable/persistence/PersistedCache.ts

@@ -1,4 +1,21 @@
 /**
+ * Persistent caching for `Persistable` request keys.
+ *
+ * A `PersistedCache` combines a scoped in-memory `Cache` with a named
+ * `Persistence` store. It is useful for expensive or idempotent lookups such as
+ * remote API calls, database reads, and request results that should be reused
+ * across fibers, process restarts, or multiple workers sharing the same backing
+ * store.
+ *
+ * The persistent `timeToLive` is evaluated for the stored `Exit`, so successes
+ * and failures can be cached with different lifetimes. The in-memory cache has
+ * its own `inMemoryTTL` and capacity, and `invalidate` removes both the
+ * persisted value and the in-memory entry. Persisted values are encoded with
+ * the key's success and error schemas and stored under the key's primary key, so
+ * schema changes, primary-key changes, or store-id collisions can make old
+ * entries fail to decode until they are invalidated or written under a new
+ * `storeId`.
+ *
  * @since 4.0.0
  */
 import * as Cache from "../../Cache.ts"
@@ -14,8 +31,10 @@ import * as Persistence from "./Persistence.ts"
 const TypeId = "~effect/persistence/PersistedCache" as const
 
 /**
+ * Cache that combines an in-memory `Cache` with a persisted backing store.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface PersistedCache<K extends Persistable.Any, out R = never> {
   readonly [TypeId]: typeof TypeId
@@ -34,8 +53,14 @@ export interface PersistedCache<K extends Persistable.Any, out R = never> {
 }
 
 /**
+ * Creates a persisted cache for `Persistable` request keys.
+ *
+ * The cache reads persisted exits before running the lookup, stores lookup
+ * exits with the configured persistent TTL, and also keeps a scoped in-memory
+ * cache with its own capacity and TTL.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make: <
   K extends Persistable.Any,