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

package/src/unstable/sql/SqlError.ts

@@ -1,4 +1,22 @@
 /**
+ * Structured SQL errors used by the unstable SQL APIs.
+ *
+ * This module defines the top-level `SqlError` wrapper, the concrete
+ * `SqlErrorReason` variants used by drivers and adapters, and helpers for
+ * recognizing and classifying database failures. It is useful when turning
+ * native driver errors into typed Effect failures, choosing retry policies from
+ * `isRetryable`, or distinguishing user-facing query problems such as syntax
+ * and constraint failures from infrastructure problems such as connection,
+ * lock, statement timeout, deadlock, and serialization failures.
+ *
+ * Query, connection, and migration code should preserve the original cause and
+ * operation metadata when constructing these errors. Retrying can be appropriate
+ * for transient connection and concurrency failures, but syntax, authorization,
+ * authentication, and constraint failures generally require changing the query,
+ * credentials, permissions, or migration data. When classifying SQLite errors,
+ * the helpers inspect `code` and `errno` values and extract unique constraint
+ * names when available.
+ *
  * @since 4.0.0
  */
 import * as Predicate from "../../Predicate.ts"
@@ -14,6 +32,9 @@ const ReasonFields = {
 }
 
 /**
+ * SQL error reason for connection or open failures; marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("effect/sql/SqlError/ConnectionError")(
@@ -21,11 +42,15 @@ export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("e
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -34,17 +59,25 @@ export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>("e
 }
 
 /**
+ * SQL error reason for authentication failures such as invalid credentials; not
+ * marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class AuthenticationError extends Schema.TaggedErrorClass<AuthenticationError>(
   "effect/sql/SqlError/AuthenticationError"
 )("AuthenticationError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -53,17 +86,25 @@ export class AuthenticationError extends Schema.TaggedErrorClass<AuthenticationE
 }
 
 /**
+ * SQL error reason for authorization or permission failures; not marked
+ * retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class AuthorizationError extends Schema.TaggedErrorClass<AuthorizationError>(
   "effect/sql/SqlError/AuthorizationError"
 )("AuthorizationError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -72,6 +113,9 @@ export class AuthorizationError extends Schema.TaggedErrorClass<AuthorizationErr
 }
 
 /**
+ * SQL error reason for invalid SQL syntax; not marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class SqlSyntaxError extends Schema.TaggedErrorClass<SqlSyntaxError>("effect/sql/SqlError/SqlSyntaxError")(
@@ -79,11 +123,15 @@ export class SqlSyntaxError extends Schema.TaggedErrorClass<SqlSyntaxError>("eff
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -97,6 +145,10 @@ const UniqueViolationFields = {
 }
 
 /**
+ * SQL error reason for a unique constraint violation, including the violated
+ * constraint identifier; not marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("effect/sql/SqlError/UniqueViolation")(
@@ -104,11 +156,15 @@ export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("e
   UniqueViolationFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -117,6 +173,9 @@ export class UniqueViolation extends Schema.TaggedErrorClass<UniqueViolation>("e
 }
 
 /**
+ * SQL error reason for a non-unique constraint violation; not marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("effect/sql/SqlError/ConstraintError")(
@@ -124,11 +183,15 @@ export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("e
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -137,6 +200,9 @@ export class ConstraintError extends Schema.TaggedErrorClass<ConstraintError>("e
 }
 
 /**
+ * SQL error reason for a database deadlock; marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effect/sql/SqlError/DeadlockError")(
@@ -144,11 +210,15 @@ export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effec
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -157,17 +227,25 @@ export class DeadlockError extends Schema.TaggedErrorClass<DeadlockError>("effec
 }
 
 /**
+ * SQL error reason for a transaction serialization or isolation conflict;
+ * marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class SerializationError extends Schema.TaggedErrorClass<SerializationError>(
   "effect/sql/SqlError/SerializationError"
 )("SerializationError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -176,6 +254,10 @@ export class SerializationError extends Schema.TaggedErrorClass<SerializationErr
 }
 
 /**
+ * SQL error reason for timing out while waiting on a database lock; marked
+ * retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>("effect/sql/SqlError/LockTimeoutError")(
@@ -183,11 +265,15 @@ export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>(
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -196,17 +282,24 @@ export class LockTimeoutError extends Schema.TaggedErrorClass<LockTimeoutError>(
 }
 
 /**
+ * SQL error reason for a statement or query timeout; marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class StatementTimeoutError extends Schema.TaggedErrorClass<StatementTimeoutError>(
   "effect/sql/SqlError/StatementTimeoutError"
 )("StatementTimeoutError", ReasonFields) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -215,6 +308,9 @@ export class StatementTimeoutError extends Schema.TaggedErrorClass<StatementTime
 }
 
 /**
+ * SQL error reason for an unclassified database failure; not marked retryable.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class UnknownError extends Schema.TaggedErrorClass<UnknownError>("effect/sql/SqlError/UnknownError")(
@@ -222,11 +318,15 @@ export class UnknownError extends Schema.TaggedErrorClass<UnknownError>("effect/
   ReasonFields
 ) {
   /**
+   * Marks this value as a structured SQL error reason for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ReasonTypeId] = ReasonTypeId
 
   /**
+   * Indicates whether retrying the failed SQL operation may succeed.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -235,6 +335,10 @@ export class UnknownError extends Schema.TaggedErrorClass<UnknownError>("effect/
 }
 
 /**
+ * Union of structured SQL error reasons, each carrying the original cause plus
+ * optional message and operation metadata.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export type SqlErrorReason =
@@ -251,6 +355,9 @@ export type SqlErrorReason =
   | UnknownError
 
 /**
+ * Schema union for encoding and decoding `SqlErrorReason` values.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export const SqlErrorReason: Schema.Union<[
@@ -280,22 +387,32 @@ export const SqlErrorReason: Schema.Union<[
 ])
 
 /**
+ * Top-level SQL error wrapper whose `message`, `cause`, and `isRetryable`
+ * values are derived from its `SqlErrorReason`.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlError")("SqlError", {
   reason: SqlErrorReason
 }) {
   /**
+   * Marks this value as the top-level SQL error wrapper for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId
 
   /**
+   * Exposes the structured SQL reason as the JavaScript error cause.
+   *
    * @since 4.0.0
    */
   override readonly cause = this.reason
 
   /**
+   * Uses the reason message when present, otherwise falls back to the reason tag.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -303,6 +420,8 @@ export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlE
   }
 
   /**
+   * Delegates retryability to the underlying SQL error reason.
+   *
    * @since 4.0.0
    */
   get isRetryable(): boolean {
@@ -311,11 +430,17 @@ export class SqlError extends Schema.TaggedErrorClass<SqlError>("effect/sql/SqlE
 }
 
 /**
+ * Returns `true` when a value is a `SqlError`.
+ *
+ * @category guards
  * @since 4.0.0
  */
 export const isSqlError = (u: unknown): u is SqlError => Predicate.hasProperty(u, TypeId)
 
 /**
+ * Returns `true` when a value is a `SqlErrorReason`.
+ *
+ * @category guards
  * @since 4.0.0
  */
 export const isSqlErrorReason = (u: unknown): u is SqlErrorReason => Predicate.hasProperty(u, ReasonTypeId)
@@ -388,6 +513,10 @@ const sqliteUniqueConstraintFromCause = (cause: unknown): string => {
 }
 
 /**
+ * Classifies a native SQLite error cause into a `SqlErrorReason` using its
+ * `code` or `errno`, with optional message and operation metadata.
+ *
+ * @category converting
  * @since 4.0.0
  */
 export const classifySqliteError = (
@@ -447,6 +576,10 @@ export const classifySqliteError = (
 }
 
 /**
+ * Error raised when an ordered batched SQL resolver receives a different number
+ * of result rows than requests.
+ *
+ * @category errors
  * @since 4.0.0
  */
 export class ResultLengthMismatch
@@ -456,6 +589,8 @@ export class ResultLengthMismatch
   })
 {
   /**
+   * Explains the mismatch between expected and actual batched SQL result counts.
+   *
    * @since 4.0.0
    */
   override get message() {

package/src/unstable/sql/SqlModel.ts

@@ -1,6 +1,22 @@
 /**
+ * Builds SQL repositories and request resolvers from Effect schema models.
+ *
+ * Use this module when a `Model` describes rows in a concrete SQL table and
+ * you want the common insert, update, find-by-id, and delete operations without
+ * hand-writing the schema encoding, row decoding, and resolver batching each
+ * time. The helpers are intended for model-backed tables where the model field
+ * names line up with the encoded table columns and the chosen `idColumn` is
+ * present in both the model fields and update schema.
+ *
+ * Returned rows are decoded with the full model schema, while insert and update
+ * requests are encoded with the model's dedicated input schemas. Soft deletes
+ * are opt-in via `softDeleteColumn`: reads and updates only see rows where that
+ * column is `null`, and deletes set it to `CURRENT_TIMESTAMP` instead of
+ * removing the row. Dialects with `returning` support return changed rows
+ * directly; MySQL performs a follow-up `select`, so generated ids, defaults,
+ * and trigger-updated values must be observable from that query.
+ *
  * @since 4.0.0
- * @category models
  */
 import type * as Cause from "../../Cause.ts"
 import * as Effect from "../../Effect.ts"
@@ -14,10 +30,13 @@ import * as SqlResolver from "./SqlResolver.ts"
 import * as SqlSchema from "./SqlSchema.ts"
 
 /**
- * Create a simple CRUD repository from a model.
+ * Creates a CRUD repository for a schema model backed by a SQL table, with
+ * insert, update, find-by-id, and delete operations. When `softDeleteColumn` is
+ * supplied, reads ignore soft-deleted rows and delete updates that column
+ * instead of removing the row.
  *
- * @since 4.0.0
  * @category repository
+ * @since 4.0.0
  */
 export const makeRepository = <
   S extends Model.Any,
@@ -210,10 +229,11 @@ select * from ${sql(options.tableName)} where ${withSoftDeleteFilter(sql`${sql(i
   })
 
 /**
- * Create some simple data loaders from a model.
+ * Creates batched request resolvers for a schema model's insert, insert-void,
+ * find-by-id, and delete operations, honoring the optional soft-delete column.
  *
- * @since 4.0.0
  * @category repository
+ * @since 4.0.0
  */
 export const makeResolvers = <
   S extends Model.Any,

package/src/unstable/sql/SqlResolver.ts

@@ -1,4 +1,30 @@
 /**
+ * Schema-aware `RequestResolver` helpers for SQL-backed data loading.
+ *
+ * This module bridges `Effect.request` with `SqlClient` by representing each
+ * lookup or mutation as a `SqlRequest` and batching concurrent requests into a
+ * single SQL operation. Request payloads are encoded with the request schema
+ * before `execute` is called, and rows returned by the query are decoded with
+ * the result schema before entries are completed.
+ *
+ * Use `ordered` when a query returns exactly one row per request in the same
+ * order, `findById` for `where id in (...)` lookups, `grouped` for one-to-many
+ * relationships, and `void` for inserts, updates, deletes, or other
+ * side-effecting statements where no row is needed.
+ *
+ * **Gotchas**
+ *
+ * - `ordered` requires the result count and order to match the request batch.
+ * - `grouped` and `findById` rely on stable request/result keys and fail
+ *   missing requests with `NoSuchElementError`.
+ * - Equal payloads are equal `SqlRequest`s, which enables request batching,
+ *   deduplication, and cache reuse; model payload identity deliberately.
+ * - Batches are split by the active SQL transaction connection, so requests
+ *   made in different transactions are not resolved together.
+ * - Queries like `where id in (...)` often return rows in database order; use
+ *   `findById` or `grouped`, or preserve input order explicitly before choosing
+ *   `ordered`.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -16,8 +42,11 @@ import * as SqlClient from "./SqlClient.ts"
 import { ResultLengthMismatch } from "./SqlError.ts"
 
 /**
- * @since 4.0.0
+ * Request type used by SQL request resolvers, carrying the input payload
+ * together with the resolver's result, error, and environment types.
+ *
  * @category requests
+ * @since 4.0.0
  */
 export interface SqlRequest<In, A, E, R> extends Request.Request<A, E | Schema.SchemaError, R> {
   readonly payload: In
@@ -37,18 +66,27 @@ const SqlRequestProto = {
 }
 
 /**
- * @since 4.0.0
+ * Submits a payload as a `SqlRequest` to a request resolver, either directly
+ * with a payload and resolver or curried by resolver.
+ *
  * @category requests
+ * @since 4.0.0
  */
 export const request: {
   /**
-   * @since 4.0.0
+   * Submits a payload as a `SqlRequest` to a request resolver, either directly
+   * with a payload and resolver or curried by resolver.
+   *
    * @category requests
+   * @since 4.0.0
    */
   <In, A, E, R>(resolver: RequestResolver.RequestResolver<SqlRequest<In, A, E, R>>): (payload: In) => Effect.Effect<A, E | Schema.SchemaError, R>
   /**
-   * @since 4.0.0
+   * Submits a payload as a `SqlRequest` to a request resolver, either directly
+   * with a payload and resolver or curried by resolver.
+   *
    * @category requests
+   * @since 4.0.0
    */
   <In, A, E, R>(
     payload: In,
@@ -63,8 +101,11 @@ export const request: {
 } as any
 
 /**
- * @since 4.0.0
+ * Constructs a `SqlRequest` from a payload. Equality and hashing are based on
+ * the payload so equal requests can be batched and deduplicated.
+ *
  * @category requests
+ * @since 4.0.0
  */
 export const SqlRequest = <In, A, E, R>(payload: In): SqlRequest<In, A, E, R> => {
   const self = Object.create(SqlRequestProto)
@@ -80,8 +121,8 @@ export const SqlRequest = <In, A, E, R>(payload: In): SqlRequest<In, A, E, R> =>
  *
  * Results are mapped to the requests in order, so the length of the results must match the length of the requests.
  *
- * @since 4.0.0
  * @category resolvers
+ * @since 4.0.0
  */
 export const ordered = <Req extends Schema.Top, Res extends Schema.Top, _, E, R>(
   options: {
@@ -124,12 +165,12 @@ export const ordered = <Req extends Schema.Top, Res extends Schema.Top, _, E, R>
 }
 
 /**
- * Create a resolver the can return multiple results for a single request.
+ * Creates a batched SQL request resolver that encodes requests, decodes result
+ * rows, groups decoded results by matching request and result keys, and fails a
+ * request with `NoSuchElementError` when no result group exists.
  *
- * Results are grouped by a common key extracted from the request and result.
- *
- * @since 4.0.0
  * @category resolvers
+ * @since 4.0.0
  */
 export const grouped = <Req extends Schema.Top, Res extends Schema.Top, K, Row, E, R>(
   options: {
@@ -193,10 +234,12 @@ export const grouped = <Req extends Schema.Top, Res extends Schema.Top, K, Row,
 }
 
 /**
- * Create a resolver that resolves results by id.
+ * Creates a batched resolver that fetches rows for encoded ids, decodes
+ * results, completes each matching request using `ResultId`, and fails missing
+ * ids with `NoSuchElementError`.
  *
- * @since 4.0.0
  * @category resolvers
+ * @since 4.0.0
  */
 export const findById = <Id extends Schema.Top, Res extends Schema.Top, Row, E, R>(
   options: {
@@ -295,8 +338,8 @@ export {
   /**
    * Create a resolver that performs side effects.
    *
-   * @since 4.0.0
    * @category resolvers
+   * @since 4.0.0
    */
   void_ as void
 }

package/src/unstable/sql/SqlSchema.ts

@@ -1,4 +1,22 @@
 /**
+ * Schema-driven helpers for wrapping SQL executions in typed query functions.
+ *
+ * This module connects `Schema` request and result definitions to an `execute`
+ * callback that runs the actual SQL statement. The returned functions accept
+ * the request schema's decoded `Type`, encode it to the SQL-facing `Encoded`
+ * shape, run the callback, and then decode unknown driver rows through the
+ * result schema. This is useful for repository methods, CRUD helpers, request
+ * resolvers, and write operations where callers should work with domain values
+ * instead of raw SQL parameters or rows.
+ *
+ * The `execute` callback always receives `Req["Encoded"]`, so schema
+ * transformations, required encoding services, and database representations
+ * such as nullable columns, JSON values, dates, and bigints must line up with
+ * the statement builder and dialect in use. Result schemas decode the rows
+ * returned by the driver after any SQL client row transforms; `findOne` and
+ * `findOneOption` only inspect the first row, `findNonEmpty` requires at least
+ * one row, and `void` discards any driver result after request encoding.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -8,10 +26,11 @@ import type * as Option from "../../Option.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
- * Run a sql query with a request schema and a result schema.
+ * Builds a query function that encodes the request, decodes all result rows,
+ * and fails with `NoSuchElementError` when the result set is empty.
  *
+ * @category constructors
  * @since 4.0.0
- * @category constructor
  */
 export const findAll = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {
@@ -34,8 +53,8 @@ export const findAll = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
 /**
  * Run a sql query with a request schema and a result schema.
  *
+ * @category constructors
  * @since 4.0.0
- * @category constructor
  */
 export const findNonEmpty = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {
@@ -74,17 +93,18 @@ export {
   /**
    * Run a sql query with a request schema and discard the result.
    *
+   * @category constructors
    * @since 4.0.0
-   * @category constructor
    */
   void_ as void
 }
 
 /**
- * Run a sql query with a request schema and a result schema and return the first result.
+ * Builds a query function that encodes the request, decodes the first result
+ * row, and fails with `NoSuchElementError` when no rows are returned.
  *
+ * @category constructors
  * @since 4.0.0
- * @category constructor
  */
 export const findOne = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {
@@ -113,10 +133,11 @@ export const findOne = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
 }
 
 /**
- * Run a sql query with a request schema and a result schema and return the first result.
+ * Builds a query function that encodes the request, decodes the first result row
+ * as `Option.some`, and returns `Option.none` when no rows are returned.
  *
+ * @category constructors
  * @since 4.0.0
- * @category constructor
  */
 export const findOneOption = <Req extends Schema.Top, Res extends Schema.Top, E, R>(
   options: {