From ae9b886dfbf8cfe8d745ede937a8f3088ec6a094 Mon Sep 17 00:00:00 2001 From: Giovanni Ravalico <15946771+suddenlyGiovanni@users.noreply.github.com> Date: Tue, 3 Sep 2024 11:38:15 +0200 Subject: [PATCH] chore(dependencies): Updated @effect/schema to 0.68.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - [#2906](https://github.com/Effect-TS/effect/pull/2906) [`f6c7977`](https://github.com/Effect-TS/effect/commit/f6c79772e632c440b7e5221bb75f0ef9d3c3b005) Thanks @gcanti! - ## Refactoring of the `ParseIssue` Model The `ParseIssue` model in the `@effect/schema/ParseResult` module has undergone a comprehensive redesign and simplification that enhances its expressiveness without compromising functionality. This section explores the motivation and details of this refactoring. ### Enhanced `Schema.filter` API The `Schema.filter` API has been improved to support more complex filtering that can involve multiple properties of a struct. This is especially useful for validations that compare two fields, such as ensuring that a `password` field matches a `confirm_password` field, a common requirement in form validations. **Previous Limitations:** Previously, while it was possible to implement a filter that compared two fields, there was no straightforward way to attach validation messages to a specific field. This posed challenges, especially in form validations where precise error reporting is crucial. **Example of Previous Implementation:** ```ts import { ArrayFormatter, Schema } from "@effect/schema" import { Either } from "effect" const Password = Schema.Trim.pipe(Schema.minLength(1)) const MyForm = Schema.Struct({ password: Password, confirm_password: Password }).pipe( Schema.filter((input) => { if (input.password !== input.confirm_password) { return "Passwords do not match" } }) ) console.log( "%o", Schema.decodeUnknownEither(MyForm)({ password: "abc", confirm_password: "d" }).pipe(Either.mapLeft((error) => ArrayFormatter.formatErrorSync(error))) ) /* { _id: 'Either', _tag: 'Left', left: [ { _tag: 'Type', path: [], message: 'Passwords do not match' } ] } */ ``` In this scenario, while the filter functionally works, the lack of a specific error path (`path: []`) means errors are not as descriptive or helpful as they could be. ### Specifying Error Paths With the new improvements, it's now possible to specify an error path along with the message, which enhances error specificity and is particularly beneficial for integration with tools like `react-hook-form`. **Updated Implementation Example:** ```ts import { ArrayFormatter, Schema } from "@effect/schema" import { Either } from "effect" const Password = Schema.Trim.pipe(Schema.minLength(1)) const MyForm = Schema.Struct({ password: Password, confirm_password: Password }).pipe( Schema.filter((input) => { if (input.password !== input.confirm_password) { return { path: ["confirm_password"], message: "Passwords do not match" } } }) ) console.log( "%o", Schema.decodeUnknownEither(MyForm)({ password: "abc", confirm_password: "d" }).pipe(Either.mapLeft((error) => ArrayFormatter.formatErrorSync(error))) ) /* { _id: 'Either', _tag: 'Left', left: [ { _tag: 'Type', path: [ 'confirm_password' ], message: 'Passwords do not match' } ] } */ ``` This modification allows the error to be directly associated with the `confirm_password` field, improving clarity for the end-user. ### Multiple Error Reporting The refactored API also supports reporting multiple issues at once, which is useful in forms where several validation checks might fail simultaneously. **Example of Multiple Issues Reporting:** ```ts import { ArrayFormatter, Schema } from "@effect/schema" import { Either } from "effect" const Password = Schema.Trim.pipe(Schema.minLength(1)) const OptionalString = Schema.optional(Schema.String) const MyForm = Schema.Struct({ password: Password, confirm_password: Password, name: OptionalString, surname: OptionalString }).pipe( Schema.filter((input) => { const issues: Array = [] // passwords must match if (input.password !== input.confirm_password) { issues.push({ path: ["confirm_password"], message: "Passwords do not match" }) } // either name or surname must be present if (!input.name && !input.surname) { issues.push({ path: ["surname"], message: "Surname must be present if name is not present" }) } return issues }) ) console.log( "%o", Schema.decodeUnknownEither(MyForm)({ password: "abc", confirm_password: "d" }).pipe(Either.mapLeft((error) => ArrayFormatter.formatErrorSync(error))) ) /* { _id: 'Either', _tag: 'Left', left: [ { _tag: 'Type', path: [ 'confirm_password' ], message: 'Passwords do not match' }, { _tag: 'Type', path: [ 'surname' ], message: 'Surname must be present if name is not present' } ] } */ ``` ### The new `ParseIssue` Model The `ParseIssue` type has undergone a significant restructuring to improve its expressiveness and simplicity. This new model categorizes issues into leaf and composite types, enhancing clarity and making error handling more systematic. **Structure of `ParseIsssue` Type:** ```ts export type ParseIssue = // leaf | Type | Missing | Unexpected | Forbidden // composite | Pointer | Refinement | Transformation | Composite ``` **Key Changes in the Model:** 1. **New Members:** - `Composite`: A new class that aggregates multiple `ParseIssue` instances. - `Missing`: Identifies when a required element or value is absent. - `Unexpected`: Flags unexpected elements or values in the input. - `Pointer`: Points to the part of the data structure where an issue occurs. 2. **Removed Members:** - Previous categories like `Declaration`, `TupleType`, `TypeLiteral`, `Union`, `Member`, `Key`, and `Index` have been consolidated under the `Composite` type for a more streamlined approach. **Definition of `Composite`:** ```ts interface Composite { readonly _tag: "Composite" readonly ast: AST.Annotated readonly actual: unknown readonly issues: ParseIssue | NonEmptyReadonlyArray readonly output?: unknown } ``` ## Refined Error Messaging System We've updated our internal function `getErrorMessage` to enhance how error messages are formatted throughout our application. This function constructs an error message that includes the reason for the error, additional details, the path to where the error occurred, and the schema's AST representation if available. **Example** ```ts import { JSONSchema, Schema } from "@effect/schema" JSONSchema.make(Schema.Struct({ a: Schema.Void })) /* throws: Error: Missing annotation at path: ["a"] details: Generating a JSON Schema for this schema requires a "jsonSchema" annotation schema (VoidKeyword): void */ ``` ## Enhancing Tuples with Element Annotations Annotations are used to add metadata to tuple elements, which can describe the purpose or requirements of each element more clearly. This can be particularly useful when generating documentation or JSON schemas from your schemas. ```ts import { JSONSchema, Schema } from "@effect/schema" // Defining a tuple with annotations for each coordinate in a point const Point = Schema.Tuple( Schema.element(Schema.Number).annotations({ title: "X", description: "X coordinate" }), Schema.optionalElement(Schema.Number).annotations({ title: "Y", description: "optional Y coordinate" }) ) // Generating a JSON Schema from the tuple console.log(JSONSchema.make(Point)) /* Output: { '$schema': 'http://json-schema.org/draft-07/schema#', type: 'array', minItems: 1, items: [ { type: 'number', description: 'X coordinate', title: 'X' }, { type: 'number', description: 'optional Y coordinate', title: 'Y' } ], additionalItems: false } */ ``` ## Missing messages You can provide custom messages for missing fields or elements using the new `missingMessage` annotation. Example (missing field) ```ts import { Schema } from "@effect/schema" const Person = Schema.Struct({ name: Schema.propertySignature(Schema.String).annotations({ missingMessage: () => "Name is required" }) }) Schema.decodeUnknownSync(Person)({}) /* Output: Error: { readonly name: string } └─ ["name"] └─ Name is required */ ``` Example (missing element) ```ts import { Schema } from "@effect/schema" const Point = Schema.Tuple( Schema.element(Schema.Number).annotations({ missingMessage: () => "X coordinate is required" }), Schema.element(Schema.Number).annotations({ missingMessage: () => "Y coordinate is required" }) ) Schema.decodeUnknownSync(Point)([], { errors: "all" }) /* Output: Error: readonly [number, number] ├─ [0] │ └─ X coordinate is required └─ [1] └─ Y coordinate is required */ ``` ## Streamlining Annotations The individual APIs that were previously used to add annotations to schemas have been removed. This change was made because these individual annotation APIs did not provide significant value and were burdensome to maintain. Instead, you can now use the `annotations` method directly or the `Schema.annotations` API for a `pipe`-able approach. Before ```ts import { Schema } from "@effect/schema" // Example of adding an identifier using a dedicated API const schema = Schema.String.pipe(Schema.identifier("myIdentitifer")) ``` Now ```ts import { Schema } from "@effect/schema" // Directly using the annotations method const schema = Schema.String.annotations({ identifier: "myIdentitifer" }) // or const schema2 = Schema.String.pipe( // Using the annotations function in a pipe-able format Schema.annotations({ identifier: "myIdentitifer" }) ) ``` ## Standardize Error Handling for `*Either`, `*Sync` and `asserts` APIs Now the `*Sync` and `asserts` APIs throw a `ParseError` while before they was throwing a simple `Error` with a `cause` containing a `ParseIssue` ```ts import { ParseResult, Schema } from "@effect/schema" try { Schema.decodeUnknownSync(Schema.String)(null) } catch (e) { console.log(ParseResult.isParseError(e)) // true } const asserts: (u: unknown) => asserts u is string = Schema.asserts( Schema.String ) try { asserts(null) } catch (e) { console.log(ParseResult.isParseError(e)) // true } ``` ## List of Changes AST - add `MissingMessageAnnotation` annotations - add `Type` - remove `verbose` option from `toString()` methods **Breaking** - rename `Element` to `OptionalType` and add an `annotations` field - change `TupleType` definition: from `rest: ReadonlyArray` to `rest: ReadonlyArray` - remove `TemplateLiteral.make` Schema - add `missingMessage` annotation to `PropertySignature` - add `FilterIssue` helper interface **Breaking** - remove `TupleType.Element` type - replace `OptionalElement` API interface with `Element` API interface - remove `PropertySignature.GetToken` - remove duplicated annotation APIs - `message` - `identifier` - `title` - `description` - `examples` - `default` - `documentation` - `jsonSchema` - `equivalence` - `concurrency` - `concurrency` - `parseIssueTitle` - remove `Secret` and `SecretFromSelf` ParseResult - add `isParseError` type guard **Breaking** - `ParseIssue` refactoring - make `Missing` and `Unexpected` parse issues - replace `Declaration` with `Composite` - remove `Union` in favour of `Composite` - remove `TypeLiteral` in favour of `Composite` - remove `TupleType` in favour of `Composite` - remove `Member` class - merge `Key` and `Index` into `Pointer` - `Type` - change `message` field from `Option` to `string | undefined` - `Refinement` - rename `error` field to `issue` - `Transformation` - rename `error` field to `issue` - `Missing` - add `ast: AST.Type` field - add `message` field - add `actual` field - `Unexpected` - replace `ast` field with a `message` field - add `actual` field - `ParseError` - rename `error` property to `issue` - remove `missing` export - Standardize Error Handling for `*Either`, `*Sync` and `asserts` APIs, closes #2968 - Updated dependencies [[`a67b8fe`](https://github.com/Effect-TS/effect/commit/a67b8fe2ace08419424811b5f0d9a5378eaea352)]: - effect@3.3.4 Signed-off-by: Giovanni Ravalico <15946771+suddenlyGiovanni@users.noreply.github.com> --- package.json | 6 ++--- pnpm-lock.yaml | 24 +++++++++---------- .../iso8601-date-string.spec.ts | 2 +- .../non-empty-string/non-empty-string.spec.ts | 2 +- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/package.json b/package.json index aef08a2..5a62d60 100644 --- a/package.json +++ b/package.json @@ -41,12 +41,12 @@ }, "license": "UNLICENSED", "peerDependencies": { - "@effect/schema": "~0.67.24" + "@effect/schema": "~0.68.0" }, "devDependencies": { "@biomejs/biome": "1.8.3", "@changesets/cli": "2.27.7", - "@effect/schema": "0.67.24", + "@effect/schema": "0.68.0", "@std/yaml": "npm:@jsr/std__yaml@1.0.4", "@tsconfig/node21": "21.0.3", "@tsconfig/strictest": "2.0.5", @@ -54,7 +54,7 @@ "@types/node": "22.5.2", "@vitest/coverage-v8": "2.0.5", "@vitest/ui": "2.0.5", - "effect": "3.3.3", + "effect": "3.3.4", "typescript": "5.6.1-rc", "vite-tsconfig-paths": "5.0.1", "vitest": "2.0.5" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4fd7ba8..c22027e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -15,8 +15,8 @@ importers: specifier: 2.27.7 version: 2.27.7 '@effect/schema': - specifier: 0.67.24 - version: 0.67.24(effect@3.3.3) + specifier: 0.68.0 + version: 0.68.0(effect@3.3.4) '@std/yaml': specifier: npm:@jsr/std__yaml@1.0.4 version: '@jsr/std__yaml@1.0.4' @@ -39,8 +39,8 @@ importers: specifier: 2.0.5 version: 2.0.5(vitest@2.0.5) effect: - specifier: 3.3.3 - version: 3.3.3 + specifier: 3.3.4 + version: 3.3.4 typescript: specifier: 5.6.1-rc version: 5.6.1-rc @@ -189,10 +189,10 @@ packages: '@changesets/write@0.3.1': resolution: {integrity: sha512-SyGtMXzH3qFqlHKcvFY2eX+6b0NGiFcNav8AFsYwy5l8hejOeoeTDemu5Yjmke2V5jpzY+pBvM0vCCQ3gdZpfw==} - '@effect/schema@0.67.24': - resolution: {integrity: sha512-IaJYTqvWxOCTio8PHHtiZALDfYkUX90lElsqtQtuCTcrR14nzxwUb1gPye5iS3rZjbcc4NiDsROBJJs4+wMP0g==} + '@effect/schema@0.68.0': + resolution: {integrity: sha512-Z4G2g4Nq5WYrPSl2mJl2SqoQBRlnoyvWrN2fQwB0u5fhrNVlnCnt6kLAuFvMDOgL6NYLgN9aPomg1opgbfxcDA==} peerDependencies: - effect: ^3.3.3 + effect: ^3.3.4 '@esbuild/aix-ppc64@0.20.2': resolution: {integrity: sha512-D+EBOJHXdNZcLJRBkhENNG8Wji2kgc9AZ9KiPr1JuZjsNtyHzrsfLRrY0tk2H2aoFu6RANO1y1iPPUCDYWkb5g==} @@ -640,8 +640,8 @@ packages: eastasianwidth@0.2.0: resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==} - effect@3.3.3: - resolution: {integrity: sha512-Rm2FwqdGVu0O/NzIPwk95r1rLj84ImWhDHJFyM+T414WBN8yb0GieDt9BZ/tgvJ/tFoPE7hc/IS+X9AjxV6CNQ==} + effect@3.3.4: + resolution: {integrity: sha512-BNQBZqe28ZlIwqKiHmEnXHx0Mql700KUk8QmXVHPwat2RhtWt28HyR86DRvc/93R6jM8AFwRRSYS/zfHI0KYIQ==} emoji-regex@8.0.0: resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==} @@ -1512,9 +1512,9 @@ snapshots: human-id: 1.0.2 prettier: 2.8.8 - '@effect/schema@0.67.24(effect@3.3.3)': + '@effect/schema@0.68.0(effect@3.3.4)': dependencies: - effect: 3.3.3 + effect: 3.3.4 fast-check: 3.18.0 '@esbuild/aix-ppc64@0.20.2': @@ -1877,7 +1877,7 @@ snapshots: eastasianwidth@0.2.0: {} - effect@3.3.3: {} + effect@3.3.4: {} emoji-regex@8.0.0: {} diff --git a/src/schema-primitive/iso8601-date-string/iso8601-date-string.spec.ts b/src/schema-primitive/iso8601-date-string/iso8601-date-string.spec.ts index fe25ade..bf6ee29 100644 --- a/src/schema-primitive/iso8601-date-string/iso8601-date-string.spec.ts +++ b/src/schema-primitive/iso8601-date-string/iso8601-date-string.spec.ts @@ -37,7 +37,7 @@ describe('ISO8601Date', () => { └─ Encoded side transformation failure └─ Date └─ Predicate refinement failure - └─ Expected Date (a valid Date), actual Invalid Date", + └─ Expected Date, actual Invalid Date", }, } `) diff --git a/src/schema-primitive/non-empty-string/non-empty-string.spec.ts b/src/schema-primitive/non-empty-string/non-empty-string.spec.ts index dd8d656..c93dc18 100644 --- a/src/schema-primitive/non-empty-string/non-empty-string.spec.ts +++ b/src/schema-primitive/non-empty-string/non-empty-string.spec.ts @@ -211,7 +211,7 @@ describe('Annotation', () => { } `) - expect(JSONSchema.make(NonEmpty.pipe(Schema.jsonSchema({ foo: 'bar' })))).not.toEqual( + expect(JSONSchema.make(NonEmpty.annotations({ jsonSchema: { foo: 'bar' } }))).not.toEqual( JSONSchema.make(NonEmpty), )