effect 4.0.0-beta.2 → 4.0.0-beta.21

package/src/JsonSchema.ts

@@ -1,4 +1,87 @@
 /**
+ * Convert JSON Schema documents between dialects (Draft-07, Draft-2020-12,
+ * OpenAPI 3.0, OpenAPI 3.1). All dialects are normalized to an internal
+ * `Document<"draft-2020-12">` representation before optional conversion to
+ * an output dialect.
+ *
+ * ## Mental model
+ *
+ * - **JsonSchema** — a plain object with string keys; represents any single
+ *   JSON Schema node.
+ * - **Dialect** — one of `"draft-07"`, `"draft-2020-12"`, `"openapi-3.1"`,
+ *   or `"openapi-3.0"`.
+ * - **Document** — a structured container holding a root `schema`, its
+ *   companion `definitions`, and the target `dialect`. Definitions are
+ *   stored separately from the root schema so they can be relocated when
+ *   converting between dialects.
+ * - **MultiDocument** — same as `Document` but carries multiple root
+ *   schemas (at least one). Useful when generating several schemas that
+ *   share a single definitions pool.
+ * - **Definitions** — a `Record<string, JsonSchema>` keyed by definition
+ *   name. The ref pointer prefix depends on the dialect.
+ * - **`from*` functions** — parse a raw JSON Schema object into the
+ *   canonical `Document<"draft-2020-12">`.
+ * - **`to*` functions** — convert from the canonical representation to a
+ *   specific output dialect.
+ *
+ * ## Common tasks
+ *
+ * - Parse a Draft-07 schema → {@link fromSchemaDraft07}
+ * - Parse a Draft-2020-12 schema → {@link fromSchemaDraft2020_12}
+ * - Parse an OpenAPI 3.1 schema → {@link fromSchemaOpenApi3_1}
+ * - Parse an OpenAPI 3.0 schema → {@link fromSchemaOpenApi3_0}
+ * - Convert to Draft-07 output → {@link toDocumentDraft07}
+ * - Convert to OpenAPI 3.1 output → {@link toMultiDocumentOpenApi3_1}
+ * - Resolve a `$ref` against definitions → {@link resolve$ref}
+ * - Inline the root `$ref` of a document → {@link resolveTopLevel$ref}
+ *
+ * ## Gotchas
+ *
+ * - All `from*` functions normalize to `Document<"draft-2020-12">`
+ *   regardless of the input dialect.
+ * - Unsupported or unrecognized JSON Schema keywords are silently dropped
+ *   during conversion.
+ * - Draft-07 tuple syntax (`items` as array + `additionalItems`) is
+ *   converted to 2020-12 form (`prefixItems` + `items`), and vice-versa.
+ * - OpenAPI 3.0 `nullable: true` is expanded into `type` arrays or
+ *   `anyOf` unions. The `nullable` keyword is removed.
+ * - OpenAPI 3.0 singular `example` is converted to `examples` (array).
+ * - {@link resolve$ref} only looks up the last segment of the ref path in
+ *   the definitions map; it does not follow arbitrary JSON Pointer paths.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Parse a Draft-07 schema and convert to Draft-07 output)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const raw: JsonSchema.JsonSchema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" }
+ *   },
+ *   required: ["name"]
+ * }
+ *
+ * // Parse into canonical form
+ * const doc = JsonSchema.fromSchemaDraft07(raw)
+ *
+ * // Convert back to Draft-07
+ * const draft07 = JsonSchema.toDocumentDraft07(doc)
+ *
+ * console.log(draft07.dialect) // "draft-07"
+ * console.log(draft07.schema) // { type: "object", properties: { name: { type: "string" } }, required: ["name"] }
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link Document}
+ * - {@link MultiDocument}
+ * - {@link fromSchemaDraft07}
+ * - {@link toDocumentDraft07}
+ * - {@link resolve$ref}
+ *
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
@@ -7,6 +90,12 @@ import * as Predicate from "./Predicate.ts"
 import * as Rec from "./Record.ts"
 
 /**
+ * A plain object representing a single JSON Schema node.
+ *
+ * This is an open record type (`[x: string]: unknown`) so it can hold any
+ * JSON Schema keyword. Most functions in this module accept or return this
+ * type.
+ *
  * @since 4.0.0
  */
 export interface JsonSchema {
@@ -14,27 +103,65 @@ export interface JsonSchema {
 }
 
 /**
+ * The set of JSON Schema dialects supported by this module.
+ *
+ * - `"draft-07"` — JSON Schema Draft-07
+ * - `"draft-2020-12"` — JSON Schema Draft 2020-12 (canonical internal form)
+ * - `"openapi-3.1"` — OpenAPI 3.1 (uses Draft 2020-12 as its schema dialect)
+ * - `"openapi-3.0"` — OpenAPI 3.0 (uses a Draft-04/07 subset with extensions)
+ *
  * @since 4.0.0
  */
 export type Dialect = "draft-07" | "draft-2020-12" | "openapi-3.1" | "openapi-3.0"
 
 /**
+ * The JSON Schema primitive type names.
+ *
  * @since 4.0.0
  */
 export type Type = "string" | "number" | "boolean" | "array" | "object" | "null" | "integer"
 
 /**
+ * A record of named JSON Schema definitions, keyed by definition name.
+ *
  * @since 4.0.0
  */
 export interface Definitions extends Record<string, JsonSchema> {}
 
 /**
- * Internal representation:
- * - `schema` is the root schema *without* the root definitions collection.
- * - Root definitions are stored in `definitions` and referenced via:
- *   - `#/$defs/<name>` for Draft-2020-12
- *   - `#/definitions/<name>` for Draft-07
- *   - `#/components/schemas/<name>` for OpenAPI 3.1 and OpenAPI 3.0
+ * A structured container for a single JSON Schema and its associated
+ * definitions.
+ *
+ * - Use when you need to carry a root schema together with its
+ *   shared definitions.
+ * - Use when converting between dialects via the `from*` / `to*` functions.
+ *
+ * The `schema` field holds the root schema *without* the definitions
+ * collection. Root definitions are stored separately in `definitions` and
+ * referenced via:
+ * - `#/$defs/<name>` for Draft-2020-12
+ * - `#/definitions/<name>` for Draft-07
+ * - `#/components/schemas/<name>` for OpenAPI 3.1 and OpenAPI 3.0
+ *
+ * **Example** (Inspecting a parsed document)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const raw: JsonSchema.JsonSchema = {
+ *   type: "string",
+ *   $defs: { Trimmed: { type: "string", minLength: 1 } }
+ * }
+ *
+ * const doc = JsonSchema.fromSchemaDraft2020_12(raw)
+ *
+ * console.log(doc.dialect)     // "draft-2020-12"
+ * console.log(doc.schema)      // { type: "string" }
+ * console.log(doc.definitions) // { Trimmed: { type: "string", minLength: 1 } }
+ * ```
+ *
+ * @see {@link MultiDocument}
+ * @see {@link fromSchemaDraft2020_12}
  *
  * @since 4.0.0
  */
@@ -45,6 +172,16 @@ export interface Document<D extends Dialect> {
 }
 
 /**
+ * Like {@link Document}, but carries multiple root schemas that share a
+ * single definitions pool. The `schemas` tuple is non-empty (at least one
+ * element).
+ *
+ * - Use when generating several schemas (e.g. request body + response body)
+ *   that reference the same set of definitions.
+ *
+ * @see {@link Document}
+ * @see {@link toMultiDocumentOpenApi3_1}
+ *
  * @since 4.0.0
  */
 export interface MultiDocument<D extends Dialect> {
@@ -54,11 +191,15 @@ export interface MultiDocument<D extends Dialect> {
 }
 
 /**
+ * The `$schema` meta-schema URI for JSON Schema Draft-07.
+ *
  * @since 4.0.0
  */
 export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema"
 
 /**
+ * The `$schema` meta-schema URI for JSON Schema Draft 2020-12.
+ *
  * @since 4.0.0
  */
 export const META_SCHEMA_URI_DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema"
@@ -68,6 +209,40 @@ const RE_DEFS = /^#\/\$defs(?=\/|$)/
 const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
 
 /**
+ * Parses a raw Draft-07 JSON Schema into a `Document<"draft-2020-12">`.
+ *
+ * - Use when you have a JSON Schema that follows Draft-07 conventions.
+ * - Converts Draft-07 tuple syntax (`items` as array + `additionalItems`)
+ *   to Draft-2020-12 form (`prefixItems` + `items`).
+ * - Rewrites `#/definitions/...` refs to `#/$defs/...`.
+ * - Extracts root-level `definitions` into the `definitions` field.
+ * - Does not mutate the input. Allocates a new `Document`.
+ * - Unsupported keywords (e.g. `if`/`then`/`else`, `$id`) are dropped.
+ *
+ * **Example** (Parsing a Draft-07 schema)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const raw: JsonSchema.JsonSchema = {
+ *   type: "object",
+ *   properties: {
+ *     tags: {
+ *       type: "array",
+ *       items: { type: "string" }
+ *     }
+ *   }
+ * }
+ *
+ * const doc = JsonSchema.fromSchemaDraft07(raw)
+ * console.log(doc.dialect) // "draft-2020-12"
+ * console.log(doc.schema.properties) // { tags: { type: "array", items: { type: "string" } } }
+ * ```
+ *
+ * @see {@link fromSchemaDraft2020_12}
+ * @see {@link fromSchemaOpenApi3_0}
+ * @see {@link toDocumentDraft07}
+ *
  * @since 4.0.0
  */
 export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
@@ -179,6 +354,32 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
 }
 
 /**
+ * Parses a raw Draft-2020-12 JSON Schema into a `Document<"draft-2020-12">`.
+ *
+ * - Use when you already have a schema in Draft-2020-12 format.
+ * - Separates `$defs` from the root schema into the `definitions` field.
+ * - Does not mutate the input. Allocates a new `Document`.
+ * - Unlike {@link fromSchemaDraft07}, this performs no keyword rewriting.
+ *
+ * **Example** (Parsing a Draft-2020-12 schema)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const raw: JsonSchema.JsonSchema = {
+ *   type: "number",
+ *   minimum: 0,
+ *   $defs: { PositiveInt: { type: "integer", minimum: 1 } }
+ * }
+ *
+ * const doc = JsonSchema.fromSchemaDraft2020_12(raw)
+ * console.log(doc.schema)      // { type: "number", minimum: 0 }
+ * console.log(doc.definitions) // { PositiveInt: { type: "integer", minimum: 1 } }
+ * ```
+ *
+ * @see {@link fromSchemaDraft07}
+ * @see {@link fromSchemaOpenApi3_1}
+ *
  * @since 4.0.0
  */
 export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"> {
@@ -191,6 +392,33 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
 }
 
 /**
+ * Parses a raw OpenAPI 3.1 JSON Schema into a `Document<"draft-2020-12">`.
+ *
+ * - Use when consuming schemas from an OpenAPI 3.1 specification.
+ * - Rewrites `#/components/schemas/...` refs to `#/$defs/...`.
+ * - Delegates to {@link fromSchemaDraft2020_12} after rewriting refs.
+ * - Does not mutate the input. Allocates a new `Document`.
+ *
+ * **Example** (Parsing an OpenAPI 3.1 schema)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const raw: JsonSchema.JsonSchema = {
+ *   type: "object",
+ *   properties: {
+ *     user: { $ref: "#/components/schemas/User" }
+ *   }
+ * }
+ *
+ * const doc = JsonSchema.fromSchemaOpenApi3_1(raw)
+ * // $ref is rewritten to Draft-2020-12 form
+ * console.log(doc.schema.properties) // { user: { $ref: "#/$defs/User" } }
+ * ```
+ *
+ * @see {@link fromSchemaOpenApi3_0}
+ * @see {@link toMultiDocumentOpenApi3_1}
+ *
  * @since 4.0.0
  */
 export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12"> {
@@ -199,6 +427,33 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
 }
 
 /**
+ * Parses a raw OpenAPI 3.0 JSON Schema into a `Document<"draft-2020-12">`.
+ *
+ * - Use when consuming schemas from an OpenAPI 3.0 specification.
+ * - Handles OpenAPI 3.0 extensions: `nullable`, singular `example`,
+ *   boolean `exclusiveMinimum`/`exclusiveMaximum`.
+ * - Normalizes the schema to Draft-07 first, then converts to
+ *   Draft-2020-12 via {@link fromSchemaDraft07}.
+ * - Does not mutate the input. Allocates a new `Document`.
+ *
+ * **Example** (Parsing an OpenAPI 3.0 nullable schema)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const raw: JsonSchema.JsonSchema = {
+ *   type: "string",
+ *   nullable: true
+ * }
+ *
+ * const doc = JsonSchema.fromSchemaOpenApi3_0(raw)
+ * // nullable is expanded into a type array
+ * console.log(doc.schema.type) // ["string", "null"]
+ * ```
+ *
+ * @see {@link fromSchemaOpenApi3_1}
+ * @see {@link fromSchemaDraft07}
+ *
  * @since 4.0.0
  */
 export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-12"> {
@@ -207,6 +462,36 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
 }
 
 /**
+ * Converts a `Document<"draft-2020-12">` to a `Document<"draft-07">`.
+ *
+ * - Use when you need to output a schema in Draft-07 format.
+ * - Rewrites `#/$defs/...` refs to `#/definitions/...`.
+ * - Converts Draft-2020-12 tuple syntax (`prefixItems` + `items`) to
+ *   Draft-07 form (`items` as array + `additionalItems`).
+ * - Converts both the root schema and all definitions.
+ * - Does not mutate the input. Allocates a new `Document`.
+ * - Unsupported Draft-2020-12 keywords are dropped.
+ *
+ * **Example** (Converting to Draft-07)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const doc = JsonSchema.fromSchemaDraft2020_12({
+ *   type: "array",
+ *   prefixItems: [{ type: "string" }, { type: "number" }],
+ *   items: { type: "boolean" }
+ * })
+ *
+ * const draft07 = JsonSchema.toDocumentDraft07(doc)
+ * console.log(draft07.dialect)                // "draft-07"
+ * console.log(draft07.schema.items)           // [{ type: "string" }, { type: "number" }]
+ * console.log(draft07.schema.additionalItems) // { type: "boolean" }
+ * ```
+ *
+ * @see {@link fromSchemaDraft07}
+ * @see {@link toMultiDocumentOpenApi3_1}
+ *
  * @since 4.0.0
  */
 export function toDocumentDraft07(document: Document<"draft-2020-12">): Document<"draft-07"> {
@@ -217,10 +502,7 @@ export function toDocumentDraft07(document: Document<"draft-2020-12">): Document
   }
 }
 
-/**
- * @since 4.0.0
- */
-export function toSchemaDraft07(schema: JsonSchema): JsonSchema {
+function toSchemaDraft07(schema: JsonSchema): JsonSchema {
   return rewrite(schema)
 
   function rewrite(node: unknown): JsonSchema {
@@ -322,6 +604,38 @@ export function toSchemaDraft07(schema: JsonSchema): JsonSchema {
 }
 
 /**
+ * Converts a `MultiDocument<"draft-2020-12">` to a
+ * `MultiDocument<"openapi-3.1">`.
+ *
+ * - Use when generating an OpenAPI 3.1 specification from internal schemas.
+ * - Rewrites `#/$defs/...` refs to `#/components/schemas/...`.
+ * - Sanitizes definition keys to match the OpenAPI component key pattern
+ *   (`^[a-zA-Z0-9.\-_]+$`), replacing invalid characters with `_`.
+ * - Updates all `$ref` pointers to use the sanitized keys.
+ * - Converts all schemas and definitions in the multi-document.
+ * - Does not mutate the input. Allocates a new `MultiDocument`.
+ *
+ * **Example** (Converting to OpenAPI 3.1)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const multi: JsonSchema.MultiDocument<"draft-2020-12"> = {
+ *   dialect: "draft-2020-12",
+ *   schemas: [{ $ref: "#/$defs/User" }],
+ *   definitions: {
+ *     User: { type: "object", properties: { name: { type: "string" } } }
+ *   }
+ * }
+ *
+ * const openapi = JsonSchema.toMultiDocumentOpenApi3_1(multi)
+ * console.log(openapi.dialect) // "openapi-3.1"
+ * console.log(openapi.schemas[0]) // { $ref: "#/components/schemas/User" }
+ * ```
+ *
+ * @see {@link toDocumentDraft07}
+ * @see {@link MultiDocument}
+ *
  * @since 4.0.0
  */
 export function toMultiDocumentOpenApi3_1(multiDocument: MultiDocument<"draft-2020-12">): MultiDocument<"openapi-3.1"> {
@@ -510,6 +824,35 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
 }
 
 /**
+ * Resolves a `$ref` string by looking up the last path segment in a
+ * definitions map.
+ *
+ * - Use when you need to dereference a `$ref` pointer to get the
+ *   actual schema it points to.
+ * - Only resolves the final segment of the ref path (e.g. `"User"` from
+ *   `"#/$defs/User"`); does not follow arbitrary JSON Pointer paths.
+ * - Returns `undefined` if the definition is not found.
+ * - Does not mutate anything. Pure function.
+ *
+ * **Example** (Resolving a $ref)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const definitions: JsonSchema.Definitions = {
+ *   User: { type: "object", properties: { name: { type: "string" } } }
+ * }
+ *
+ * const result = JsonSchema.resolve$ref("#/$defs/User", definitions)
+ * console.log(result) // { type: "object", properties: { name: { type: "string" } } }
+ *
+ * const missing = JsonSchema.resolve$ref("#/$defs/Unknown", definitions)
+ * console.log(missing) // undefined
+ * ```
+ *
+ * @see {@link resolveTopLevel$ref}
+ * @see {@link Definitions}
+ *
  * @since 4.0.0
  */
 export function resolve$ref($ref: string, definitions: Definitions): JsonSchema | undefined {
@@ -524,6 +867,36 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
 }
 
 /**
+ * If the root schema of a document is a `$ref`, resolves it against the
+ * document's definitions and returns a new document with the inlined
+ * schema. Returns the original document unchanged if the root schema is
+ * not a `$ref` or if the referenced definition is not found.
+ *
+ * - Use to dereference a top-level `$ref` before inspecting the root
+ *   schema's properties directly.
+ * - Does not mutate the input. Returns the same object if no change is
+ *   needed, or a shallow copy with the resolved schema.
+ *
+ * **Example** (Resolving a top-level $ref)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const doc: JsonSchema.Document<"draft-2020-12"> = {
+ *   dialect: "draft-2020-12",
+ *   schema: { $ref: "#/$defs/User" },
+ *   definitions: {
+ *     User: { type: "object", properties: { name: { type: "string" } } }
+ *   }
+ * }
+ *
+ * const resolved = JsonSchema.resolveTopLevel$ref(doc)
+ * console.log(resolved.schema) // { type: "object", properties: { name: { type: "string" } } }
+ * ```
+ *
+ * @see {@link resolve$ref}
+ * @see {@link Document}
+ *
  * @since 4.0.0
  */
 export function resolveTopLevel$ref(document: Document<"draft-2020-12">): Document<"draft-2020-12"> {

package/src/Latch.ts

@@ -0,0 +1,112 @@
+/**
+ * @since 3.8.0
+ */
+import type * as Effect from "./Effect.ts"
+import * as internal from "./internal/effect.ts"
+
+/**
+ * @category models
+ * @since 3.8.0
+ * @example
+ * ```ts
+ * import { Effect, Latch } from "effect"
+ *
+ * // Create and use a latch for coordination between fibers
+ * const program = Effect.gen(function*() {
+ *   const latch = yield* Latch.make()
+ *
+ *   // Wait for the latch to be opened
+ *   yield* latch.await
+ *
+ *   return "Latch was opened!"
+ * })
+ * ```
+ */
+export interface Latch {
+  /** open the latch, releasing all fibers waiting on it */
+  readonly open: Effect.Effect<boolean>
+  /** open the latch, releasing all fibers waiting on it */
+  readonly openUnsafe: () => boolean
+  /** release all fibers waiting on the latch, without opening it */
+  readonly release: Effect.Effect<boolean>
+  /** wait for the latch to be opened */
+  readonly await: Effect.Effect<void>
+  /** close the latch */
+  readonly close: Effect.Effect<boolean>
+  /** close the latch */
+  readonly closeUnsafe: () => boolean
+  /** only run the given effect when the latch is open */
+  readonly whenOpen: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+}
+
+/**
+ * Creates a new Latch unsafely.
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `Effect.makeLatchUnsafe`
+ *
+ * @example
+ * ```ts
+ * import { Effect, Latch } from "effect"
+ *
+ * const latch = Latch.makeUnsafe(false)
+ *
+ * const waiter = Effect.gen(function*() {
+ *   yield* Effect.log("Waiting for latch to open...")
+ *   yield* latch.await
+ *   yield* Effect.log("Latch opened! Continuing...")
+ * })
+ *
+ * const opener = Effect.gen(function*() {
+ *   yield* Effect.sleep("2 seconds")
+ *   yield* Effect.log("Opening latch...")
+ *   yield* latch.open
+ * })
+ *
+ * const program = Effect.all([waiter, opener])
+ * ```
+ *
+ * @category constructors
+ * @since 3.8.0
+ */
+export const makeUnsafe: (open?: boolean | undefined) => Latch = internal.makeLatchUnsafe
+
+/**
+ * Creates a new Latch.
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `Effect.makeLatch`
+ *
+ * @example
+ * ```ts
+ * import { Effect, Latch } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const latch = yield* Latch.make(false)
+ *
+ *   const waiter = Effect.gen(function*() {
+ *     yield* Effect.log("Waiting for latch to open...")
+ *     yield* latch.await
+ *     yield* Effect.log("Latch opened! Continuing...")
+ *   })
+ *
+ *   const opener = Effect.gen(function*() {
+ *     yield* Effect.sleep("2 seconds")
+ *     yield* Effect.log("Opening latch...")
+ *     yield* latch.open
+ *   })
+ *
+ *   yield* Effect.all([waiter, opener])
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 3.8.0
+ */
+export const make: (open?: boolean | undefined) => Effect.Effect<Latch> = internal.makeLatch