refactor optional APIs (default values and optional fields as Options) (

#247)

.changeset/hip-cups-sleep.md

@@ -0,0 +1,5 @@
+---
+"@effect/schema": minor
+---
+
+update to latest @effect/io

.changeset/tame-candles-sing.md

@@ -0,0 +1,5 @@
+---
+"@effect/schema": minor
+---
+
+refactor optional APIs (Default values and Optional fields as `Option`s)

README.md

@@ -848,7 +848,7 @@ Optional fields can be configured to accept a default value, making the field op
 
 ```ts
 // $ExpectType Schema<{ readonly a?: number; }, { readonly a: number; }>
-const schema = S.struct({ a. S.optional.withDefault(S.number, () => 0) });
+const schema = S.struct({ a. S.optional(S.number).withDefault(() => 0) });
 
 const parse = S.parse(schema)
 
@@ -869,7 +869,7 @@ Optional fields can be configured to transform a value of type `A` into `Option<
 import * as O from "@effect/data/Option"
 
 // $ExpectType Schema<{ readonly a?: number; }, { readonly a: Option<number>; }>
-const schema = S.struct({ a. S.optional.toOption(S.number) });
+const schema = S.struct({ a. S.optional(S.number).toOption() });
 
 const parse = S.parse(schema)
 

docs/modules/AST.ts.md

@@ -82,6 +82,7 @@ Added in v1.0.0
 - [model](#model)
   - [AST (type alias)](#ast-type-alias)
   - [Annotated (interface)](#annotated-interface)
+  - [Annotations (interface)](#annotations-interface)
   - [AnyKeyword (interface)](#anykeyword-interface)
   - [BigIntKeyword (interface)](#bigintkeyword-interface)
   - [BooleanKeyword (interface)](#booleankeyword-interface)
@@ -864,12 +865,22 @@ Added in v1.0.0
 
 ```ts
 export interface Annotated {
-  readonly annotations: Record<string | symbol, unknown>
+  readonly annotations: Annotations
 }
 ```
 
 Added in v1.0.0
 
+## Annotations (interface)
+
+**Signature**
+
+```ts
+export interface Annotations extends Record<string | symbol, unknown> {}
+```
+
+Added in v1.0.0
+
 ## AnyKeyword (interface)
 
 **Signature**

docs/modules/Schema.ts.md

@@ -85,6 +85,7 @@ Added in v1.0.0
   - [json](#json)
   - [literal](#literal)
   - [make](#make)
+  - [propertySignature](#propertysignature)
   - [readonlyMapFromSelf](#readonlymapfromself)
   - [readonlySetFromSelf](#readonlysetfromself)
   - [templateLiteral](#templateliteral)
@@ -199,13 +200,12 @@ Added in v1.0.0
   - [UUIDTypeId](#uuidtypeid)
   - [ValidDateTypeId](#validdatetypeid)
 - [utils](#utils)
+  - [FromOptionalKeys (type alias)](#fromoptionalkeys-type-alias)
   - [Join (type alias)](#join-type-alias)
-  - [OptionalKeys (type alias)](#optionalkeys-type-alias)
   - [PropertySignature (interface)](#propertysignature-interface)
-  - [PropertySignatureId](#propertysignatureid)
-  - [PropertySignatureId (type alias)](#propertysignatureid-type-alias)
   - [Spread (type alias)](#spread-type-alias)
   - [ToAsserts](#toasserts)
+  - [ToOptionalKeys (type alias)](#tooptionalkeys-type-alias)
   - [from](#from)
   - [getPropertySignatures](#getpropertysignatures)
   - [optional](#optional)
@@ -675,7 +675,7 @@ export declare const declare: (
   decode: (
     ...typeParameters: ReadonlyArray<Schema<any>>
   ) => (input: unknown, options?: ParseOptions | undefined) => ParseResult<any>,
-  annotations?: Record<string | symbol, unknown> | undefined
+  annotations?: AST.Annotations | undefined
 ) => Schema<any>
 ```
 
@@ -778,10 +778,7 @@ Added in v1.0.0
 **Signature**
 
 ```ts
-export declare const lazy: <I, A = I>(
-  f: () => Schema<I, A>,
-  annotations?: Record<string | symbol, unknown> | undefined
-) => Schema<I, A>
+export declare const lazy: <I, A = I>(f: () => Schema<I, A>, annotations?: AST.Annotations | undefined) => Schema<I, A>
 ```
 
 Added in v1.0.0
@@ -950,20 +947,20 @@ export declare const struct: <
     string | number | symbol,
     | Schema<any, any>
     | Schema<never, never>
-    | PropertySignature<any, any, boolean>
-    | PropertySignature<never, never, boolean>
+    | PropertySignature<any, boolean, any, boolean>
+    | PropertySignature<never, boolean, never, boolean>
   >
 >(
   fields: Fields
 ) => Schema<
   Spread<
-    { readonly [K in Exclude<keyof Fields, OptionalKeys<Fields, boolean>>]: From<Fields[K]> } & {
-      readonly [K in OptionalKeys<Fields, boolean>]?: From<Fields[K]> | undefined
+    { readonly [K in Exclude<keyof Fields, FromOptionalKeys<Fields>>]: From<Fields[K]> } & {
+      readonly [K in FromOptionalKeys<Fields>]?: From<Fields[K]> | undefined
     }
   >,
   Spread<
-    { readonly [K in Exclude<keyof Fields, OptionalKeys<Fields, true>>]: To<Fields[K]> } & {
-      readonly [K in OptionalKeys<Fields, true>]?: To<Fields[K]> | undefined
+    { readonly [K in Exclude<keyof Fields, ToOptionalKeys<Fields>>]: To<Fields[K]> } & {
+      readonly [K in ToOptionalKeys<Fields>]?: To<Fields[K]> | undefined
     }
   >
 >
@@ -1115,6 +1112,19 @@ export declare const make: <I, A>(ast: AST.AST) => Schema<I, A>
 
 Added in v1.0.0
 
+## propertySignature
+
+**Signature**
+
+```ts
+export declare const propertySignature: <I, A>(
+  schema: Schema<I, A>,
+  annotations?: AST.Annotations | undefined
+) => PropertySignature<I, false, A, false>
+```
+
+Added in v1.0.0
+
 ## readonlyMapFromSelf
 
 **Signature**
@@ -1157,7 +1167,7 @@ Added in v1.0.0
 ```ts
 export declare const uniqueSymbol: <S extends symbol>(
   symbol: S,
-  annotations?: Record<string | symbol, unknown> | undefined
+  annotations?: AST.Annotations | undefined
 ) => Schema<S, S>
 ```
 
@@ -2303,30 +2313,30 @@ Added in v1.0.0
 
 # utils
 
-## Join (type alias)
+## FromOptionalKeys (type alias)
 
 **Signature**
 
 ```ts
-export type Join<T> = T extends [infer Head, ...infer Tail]
-  ? `${Head & (string | number | bigint | boolean | null | undefined)}${Tail extends [] ? '' : Join<Tail>}`
-  : never
+export type FromOptionalKeys<Fields> = {
+  [K in keyof Fields]: Fields[K] extends
+    | PropertySignature<any, true, any, boolean>
+    | PropertySignature<never, true, never, boolean>
+    ? K
+    : never
+}[keyof Fields]
 ```
 
 Added in v1.0.0
 
-## OptionalKeys (type alias)
+## Join (type alias)
 
 **Signature**
 
 ```ts
-export type OptionalKeys<Fields, ToIsOptional extends boolean> = {
-  [K in keyof Fields]: Fields[K] extends
-    | PropertySignature<any, any, ToIsOptional>
-    | PropertySignature<never, never, ToIsOptional>
-    ? K
-    : never
-}[keyof Fields]
+export type Join<T> = T extends [infer Head, ...infer Tail]
+  ? `${Head & (string | number | bigint | boolean | null | undefined)}${Tail extends [] ? '' : Join<Tail>}`
+  : never
 ```
 
 Added in v1.0.0
@@ -2336,42 +2346,19 @@ Added in v1.0.0
 **Signature**
 
 ```ts
-export interface PropertySignature<From, To = From, ToIsOptional extends boolean = boolean> {
+export interface PropertySignature<From, FromIsOptional, To, ToIsOptional> {
   readonly From: (_: From) => From
+  readonly FromIsOptional: FromIsOptional
   readonly To: (_: To) => To
   readonly ToIsOptional: ToIsOptional
-  readonly _id: PropertySignatureId
-  readonly options?:
-    | { readonly to: 'Option' }
-    | {
-        readonly to: 'default'
-        readonly value: LazyArg<unknown>
-      }
+  readonly optional: () => PropertySignature<From, true, To, true>
+  readonly withDefault: (value: () => To) => PropertySignature<From, true, To, false>
+  readonly toOption: () => PropertySignature<From, true, Option<To>, false>
 }
 ```
 
 Added in v1.0.0
 
-## PropertySignatureId
-
-**Signature**
-
-```ts
-export declare const PropertySignatureId: typeof PropertySignatureId
-```
-
-Added in v1.0.0
-
-## PropertySignatureId (type alias)
-
-**Signature**
-
-```ts
-export type PropertySignatureId = typeof PropertySignatureId
-```
-
-Added in v1.0.0
-
 ## Spread (type alias)
 
 **Signature**
@@ -2396,6 +2383,22 @@ export declare const ToAsserts: P.ToAsserts<S>
 
 Added in v1.0.0
 
+## ToOptionalKeys (type alias)
+
+**Signature**
+
+```ts
+export type ToOptionalKeys<Fields> = {
+  [K in keyof Fields]: Fields[K] extends
+    | PropertySignature<any, boolean, any, true>
+    | PropertySignature<never, boolean, never, true>
+    ? K
+    : never
+}[keyof Fields]
+```
+
+Added in v1.0.0
+
 ## from
 
 **Signature**
@@ -2445,14 +2448,10 @@ Added in v1.0.0
 **Signature**
 
 ```ts
-export declare const optional: {
-  <I, A>(schema: Schema<I, A>): PropertySignature<I, A, true>
-  toOption: <I, A>(schema: Schema<I, A>) => PropertySignature<I, Option<A>, false>
-  withDefault: {
-    <A>(value: LazyArg<A>): <I>(schema: Schema<I, A>) => PropertySignature<I, A, false>
-    <I, A>(schema: Schema<I, A>, value: LazyArg<A>): PropertySignature<I, A, false>
-  }
-}
+export declare const optional: <I, A>(
+  schema: Schema<I, A>,
+  annotations?: AST.Annotations | undefined
+) => PropertySignature<I, true, A, true>
 ```
 
 Added in v1.0.0

dtslint/ts4.9/Schema.ts

@@ -255,32 +255,32 @@ S.struct({ a: pipe(S.string, S.optional) })
  S.struct({ a: S.optional(S.never) })
 
 // ---------------------------------------------
-// optional.withDefault
+// optional().withDefault()
 // ---------------------------------------------
 
 // $ExpectType Schema<{ readonly a: string; readonly b: number; readonly c?: boolean; }, { readonly a: string; readonly b: number; readonly c: boolean; }>
-S.struct({ a: S.string, b: S.number, c: S.optional.withDefault(S.boolean, () => false) });
+S.struct({ a: S.string, b: S.number, c: S.optional(S.boolean).withDefault(() => false) });
 
 // $ExpectType Schema<{ readonly a: string; readonly b: number; readonly c?: string; }, { readonly a: string; readonly b: number; readonly c: number; }>
-S.struct({ a: S.string, b: S.number, c: S.optional.withDefault(NumberFromString, () => 0) });
+S.struct({ a: S.string, b: S.number, c: S.optional(NumberFromString).withDefault(() => 0) });
 
 // piping
 // $ExpectType Schema<{ readonly a?: string; }, { readonly a: string; }>
-S.struct({ a: pipe(S.string, S.optional.withDefault(() => '')) })
+S.struct({ a: pipe(S.string, S.optional).withDefault(() => '') })
 
 // ---------------------------------------------
-// optional.toOption
+// optional().toOption()
 // ---------------------------------------------
 
 // $ExpectType Schema<{ readonly a: string; readonly b: number; readonly c?: boolean; }, { readonly a: string; readonly b: number; readonly c: Option<boolean>; }>
-S.struct({ a: S.string, b: S.number, c: S.optional.toOption(S.boolean) });
+S.struct({ a: S.string, b: S.number, c: S.optional(S.boolean).toOption() });
 
 // $ExpectType Schema<{ readonly a: string; readonly b: number; readonly c?: string; }, { readonly a: string; readonly b: number; readonly c: Option<number>; }>
-S.struct({ a: S.string, b: S.number, c: S.optional.toOption(NumberFromString) });
+S.struct({ a: S.string, b: S.number, c: S.optional(NumberFromString).toOption() });
 
 // piping
 // $ExpectType Schema<{ readonly a?: string; }, { readonly a: Option<string>; }>
-S.struct({ a: pipe(S.string, S.optional.toOption) })
+S.struct({ a: pipe(S.string, S.optional).toOption() })
 
 // ---------------------------------------------
 // pick

package.json

@@ -107,7 +107,7 @@
   },
   "dependencies": {
     "@effect/data": "^0.12.2",
-    "@effect/io": "^0.22.2",
+    "@effect/io": "^0.24.2",
     "fast-check": "^3.8.0"
   },
   "pnpm": {

src/AST.ts

@@ -161,12 +161,18 @@ export const DocumentationAnnotationId = "@effect/schema/DocumentationAnnotation
 // models
 // ---------------------------------------------
 
+/**
+ * @category model
+ * @since 1.0.0
+ */
+export interface Annotations extends Record<string | symbol, unknown> {}
+
 /**
  * @category model
  * @since 1.0.0
  */
 export interface Annotated {
-  readonly annotations: Record<string | symbol, unknown>
+  readonly annotations: Annotations
 }
 
 /**