Schema: rename lazy to suspend (to align with Effect.suspend), closes… (

#636)
Effect-TS · Dec 7, 2023 · deddf6e · deddf6e
1 parent 30802d5
commit deddf6e
Show file tree

Hide file tree

Showing 33 changed files with 396 additions and 336 deletions.
diff --git a/.changeset/sixty-zebras-sit.md b/.changeset/sixty-zebras-sit.md
@@ -0,0 +1,5 @@
+---
+"@effect/schema": minor
+---
+
+Schema: rename lazy to suspend (to align with Effect.suspend)
diff --git a/README.md b/README.md
@@ -774,12 +774,10 @@ interface Category {
   readonly categories: ReadonlyArray<Category>;
 }
 
-const schema: S.Schema<Category> = S.lazy<Category>(() =>
-  S.struct({
-    name: S.string,
-    categories: S.array(schema),
-  })
-).pipe(S.identifier("Category"));
+const schema: S.Schema<Category> = S.struct({
+  name: S.string,
+  categories: S.array(S.suspend(() => schema).pipe(S.identifier("Category"))),
+});
 
 const jsonSchema = JSONSchema.to(schema);
 
@@ -816,7 +814,7 @@ Output:
 */
 ```
 
-In the example above, we define a schema for a "Category" that can contain a "name" (a string) and an array of nested "categories." To support recursive definitions, we use the `S.lazy` function and identifier annotations to name our schema.
+In the example above, we define a schema for a "Category" that can contain a "name" (a string) and an array of nested "categories." To support recursive definitions, we use the `S.suspend` function and identifier annotations to name our schema.
 
 This ensures that the JSON Schema properly handles the recursive structure and creates distinct definitions for each annotated schema, improving readability and maintainability.
 
@@ -1545,7 +1543,7 @@ The class constructor itself is a Schema, and can be assigned/provided anywhere
 
 ```ts
 // $ExpectType Schema<{ readonly id: number; name: string; }, Person>
-S.lazy(() => Person);
+S.suspend(() => Person);
 
 // $ExpectType Schema<{ readonly id: number; name: string; }, { readonly id: number; name: string; }>
 Person.struct;
@@ -1827,7 +1825,7 @@ S.instanceOf(Test);
 
 ## Recursive types
 
-The `lazy` combinator is useful when you need to define a `Schema` that depends on itself, like in the case of recursive data structures. In this example, the `Category` schema depends on itself because it has a field `subcategories` that is an array of `Category` objects.
+The `suspend` combinator is useful when you need to define a `Schema` that depends on itself, like in the case of recursive data structures. In this example, the `Category` schema depends on itself because it has a field `subcategories` that is an array of `Category` objects.
 
 ```ts
 import * as S from "@effect/schema/Schema";
@@ -1837,12 +1835,10 @@ interface Category {
   readonly subcategories: ReadonlyArray<Category>;
 }
 
-const Category: S.Schema<Category> = S.lazy(() =>
-  S.struct({
-    name: S.string,
-    subcategories: S.array(Category),
-  })
-);
+const Category: S.Schema<Category> = S.struct({
+  name: S.string,
+  subcategories: S.array(S.suspend(() => Category)),
+});
 ```
 
 Here's an example of two mutually recursive schemas, `Expression` and `Operation`, that represent a simple arithmetic expression tree.
@@ -1862,21 +1858,20 @@ interface Operation {
   readonly right: Expression;
 }
 
-const Expression: S.Schema<Expression> = S.lazy(() =>
-  S.struct({
-    type: S.literal("expression"),
-    value: S.union(S.number, Operation),
-  })
-);
+const Expression: S.Schema<Expression> = S.struct({
+  type: S.literal("expression"),
+  value: S.union(
+    S.number,
+    S.suspend(() => Operation)
+  ),
+});
 
-const Operation: S.Schema<Operation> = S.lazy(() =>
-  S.struct({
-    type: S.literal("operation"),
-    operator: S.union(S.literal("+"), S.literal("-")),
-    left: Expression,
-    right: Expression,
-  })
-);
+const Operation: S.Schema<Operation> = S.struct({
+  type: S.literal("operation"),
+  operator: S.union(S.literal("+"), S.literal("-")),
+  left: Expression,
+  right: Expression,
+});
 ```
 
 ## Transformations

diff --git a/docs/modules/AST.ts.md b/docs/modules/AST.ts.md
@@ -52,10 +52,10 @@ Added in v1.0.0
   - [createEnums](#createenums)
   - [createFinalPropertySignatureTransformation](#createfinalpropertysignaturetransformation)
   - [createFinalTransformation](#createfinaltransformation)
-  - [createLazy](#createlazy)
   - [createLiteral](#createliteral)
   - [createPropertySignatureTransform](#createpropertysignaturetransform)
   - [createRefinement](#createrefinement)
+  - [createSuspend](#createsuspend)
   - [createTemplateLiteral](#createtemplateliteral)
   - [createTuple](#createtuple)
   - [createTypeLiteral](#createtypeliteral)
@@ -81,13 +81,13 @@ Added in v1.0.0
   - [isBooleanKeyword](#isbooleankeyword)
   - [isDeclaration](#isdeclaration)
   - [isEnums](#isenums)
-  - [isLazy](#islazy)
   - [isLiteral](#isliteral)
   - [isNeverKeyword](#isneverkeyword)
   - [isNumberKeyword](#isnumberkeyword)
   - [isObjectKeyword](#isobjectkeyword)
   - [isRefinement](#isrefinement)
   - [isStringKeyword](#isstringkeyword)
+  - [isSuspend](#issuspend)
   - [isSymbolKeyword](#issymbolkeyword)
   - [isTemplateLiteral](#istemplateliteral)
   - [isTransform](#istransform)
@@ -108,7 +108,6 @@ Added in v1.0.0
   - [Enums (interface)](#enums-interface)
   - [FinalPropertySignatureTransformation (interface)](#finalpropertysignaturetransformation-interface)
   - [FinalTransformation (interface)](#finaltransformation-interface)
-  - [Lazy (interface)](#lazy-interface)
   - [Literal (interface)](#literal-interface)
   - [LiteralValue (type alias)](#literalvalue-type-alias)
   - [NeverKeyword (interface)](#neverkeyword-interface)
@@ -119,6 +118,7 @@ Added in v1.0.0
   - [PropertySignatureTransformation (type alias)](#propertysignaturetransformation-type-alias)
   - [Refinement (interface)](#refinement-interface)
   - [StringKeyword (interface)](#stringkeyword-interface)
+  - [Suspend (interface)](#suspend-interface)
   - [SymbolKeyword (interface)](#symbolkeyword-interface)
   - [TemplateLiteral (interface)](#templateliteral-interface)
   - [Transform (interface)](#transform-interface)
@@ -565,16 +565,6 @@ export declare const createFinalTransformation: (
 
 Added in v1.0.0
 
-## createLazy
-
-**Signature**
-
-```ts
-export declare const createLazy: (f: () => AST, annotations?: Annotated["annotations"]) => Lazy
-```
-
-Added in v1.0.0
-
 ## createLiteral
 
 **Signature**
@@ -613,6 +603,16 @@ export declare const createRefinement: <From extends AST>(
 
 Added in v1.0.0
 
+## createSuspend
+
+**Signature**
+
+```ts
+export declare const createSuspend: (f: () => AST, annotations?: Annotated["annotations"]) => Suspend
+```
+
+Added in v1.0.0
+
 ## createTemplateLiteral
 
 **Signature**
@@ -864,16 +864,6 @@ export declare const isEnums: (ast: AST) => ast is Enums
 
 Added in v1.0.0
 
-## isLazy
-
-**Signature**
-
-```ts
-export declare const isLazy: (ast: AST) => ast is Lazy
-```
-
-Added in v1.0.0
-
 ## isLiteral
 
 **Signature**
@@ -934,6 +924,16 @@ export declare const isStringKeyword: (ast: AST) => ast is StringKeyword
 
 Added in v1.0.0
 
+## isSuspend
+
+**Signature**
+
+```ts
+export declare const isSuspend: (ast: AST) => ast is Suspend
+```
+
+Added in v1.0.0
+
 ## isSymbolKeyword
 
 **Signature**
@@ -1063,7 +1063,7 @@ export type AST =
   | Tuple
   | TypeLiteral
   | Union
-  | Lazy
+  | Suspend
   // transformations
   | Transform
 ```
@@ -1189,19 +1189,6 @@ export interface FinalTransformation {
 
 Added in v1.0.0
 
-## Lazy (interface)
-
-**Signature**
-
-```ts
-export interface Lazy extends Annotated {
-  readonly _tag: "Lazy"
-  readonly f: () => AST
-}
-```
-
-Added in v1.0.0
-
 ## Literal (interface)
 
 **Signature**
@@ -1326,6 +1313,19 @@ export interface StringKeyword extends Annotated {
 
 Added in v1.0.0
 
+## Suspend (interface)
+
+**Signature**
+
+```ts
+export interface Suspend extends Annotated {
+  readonly _tag: "Suspend"
+  readonly f: () => AST
+}
+```
+
+Added in v1.0.0
+
 ## SymbolKeyword (interface)
 
 **Signature**

diff --git a/docs/modules/Schema.ts.md b/docs/modules/Schema.ts.md
@@ -144,7 +144,6 @@ Added in v1.0.0
   - [extend](#extend)
   - [filter](#filter)
   - [keyof](#keyof)
-  - [lazy](#lazy)
   - [mutable](#mutable)
   - [nonEmptyArray](#nonemptyarray)
   - [nullable](#nullable)
@@ -156,6 +155,7 @@ Added in v1.0.0
   - [required](#required)
   - [rest](#rest)
   - [struct](#struct)
+  - [suspend](#suspend)
   - [transform](#transform)
   - [transformOrFail](#transformorfail)
   - [tuple](#tuple)
@@ -1877,16 +1877,6 @@ export declare const keyof: <I, A>(schema: Schema<I, A>) => Schema<keyof A, keyo
 
 Added in v1.0.0
 
-## lazy
-
-**Signature**
-
-```ts
-export declare const lazy: <I, A = I>(f: () => Schema<I, A>, annotations?: AST.Annotated["annotations"]) => Schema<I, A>
-```
-
-Added in v1.0.0
-
 ## mutable
 
 Creates a new schema with shallow mutability applied to its properties.
@@ -2020,6 +2010,19 @@ export declare const struct: <Fields extends StructFields>(
 
 Added in v1.0.0
 
+## suspend
+
+**Signature**
+
+```ts
+export declare const suspend: <I, A = I>(
+  f: () => Schema<I, A>,
+  annotations?: AST.Annotated["annotations"]
+) => Schema<I, A>
+```
+
+Added in v1.0.0
+
 ## transform
 
 Create a new `Schema` by transforming the input and output of an existing `Schema`

diff --git a/dtslint/Schema.ts b/dtslint/Schema.ts
@@ -422,19 +422,17 @@ S.extend(S.struct({ a: S.string, b: S.string }), S.struct({ c: S.string }))
 // );
 
 // ---------------------------------------------
-// lazy
+// suspend
 // ---------------------------------------------
 
-interface LazyTo1 {
+interface SuspendTo1 {
   readonly a: number
-  readonly as: ReadonlyArray<LazyTo1>
+  readonly as: ReadonlyArray<SuspendTo1>
 }
-const lazy1: S.Schema<LazyTo1> = S.lazy(() =>
-  S.struct({
+const suspend1: S.Schema<SuspendTo1> = S.struct({
     a: S.number,
-    as: S.array(lazy1)
+    as: S.array(S.suspend(() => suspend1))
   })
-)
 
 interface LazyFrom2 {
   readonly a: string
@@ -444,12 +442,12 @@ interface LazyTo2 {
   readonly a: number
   readonly as: ReadonlyArray<LazyTo2>
 }
-const lazy2: S.Schema<LazyFrom2, LazyTo2> = S.lazy(() =>
+const lazy2: S.Schema<LazyFrom2, LazyTo2> =
   S.struct({
     a: S.NumberFromString,
-    as: S.array(lazy2)
+    as: S.array(S.suspend(() => lazy2))
   })
-)
+
 
 // ---------------------------------------------
 // rename
@@ -638,7 +636,7 @@ S.mutable(S.union(S.struct({ a: S.number }), S.array(S.string)))
 S.mutable(S.array(S.string).pipe(S.maxItems(2)))
 
 // $ExpectType Schema<string[], string[]>
-S.mutable(S.lazy(() => S.array(S.string)))
+S.mutable(S.suspend(() => S.array(S.string)))
 
 // $ExpectType Schema<string[], string[]>
 S.mutable(S.transform(S.array(S.string), S.array(S.string), identity, identity))