Merge pull request #9 from vbudovski/feature/error-messages

Feature/error messages
vbudovski · Dec 22, 2024 · 0bbf5a7 · 0bbf5a7
2 parents 9276ae5 + 81652ef
commit 0bbf5a7
Show file tree

Hide file tree

Showing 68 changed files with 1,780 additions and 2,185 deletions.
diff --git a/paseri-docs/package.json b/paseri-docs/package.json
@@ -11,12 +11,12 @@
     "astro": "astro"
   },
   "devDependencies": {
-    "@astrojs/check": "^0.8.1",
-    "@astrojs/starlight": "^0.25.1",
-    "astro": "^4.10.2",
+    "@astrojs/check": "^0.9.4",
+    "@astrojs/starlight": "^0.30.1",
+    "astro": "^5.0.5",
     "rehype-external-links": "^3.0.0",
-    "sharp": "^0.32.5",
-    "typescript": "^5.5.3"
+    "sharp": "^0.33.5",
+    "typescript": "^5.7.2"
   },
   "packageManager": "[email protected]+sha256.dae0f7e822c56b20979bb5965e3b73b8bdabb6b8b8ef121da6d857508599ca35"
 }
diff --git a/paseri-docs/pnpm-lock.yaml b/paseri-docs/pnpm-lock.yaml
diff --git a/...tent/docs/reference/Collections/array.mdx → ...cs/reference/Schema/Collections/array.mdx b/...tent/docs/reference/Collections/array.mdx → ...cs/reference/Schema/Collections/array.mdx
diff --git a/...ontent/docs/reference/Collections/map.mdx → ...docs/reference/Schema/Collections/map.mdx b/...ontent/docs/reference/Collections/map.mdx → ...docs/reference/Schema/Collections/map.mdx
diff --git a/...ent/docs/reference/Collections/object.mdx → ...s/reference/Schema/Collections/object.mdx b/...ent/docs/reference/Collections/object.mdx → ...s/reference/Schema/Collections/object.mdx
diff --git a/...ent/docs/reference/Collections/record.mdx → ...s/reference/Schema/Collections/record.mdx b/...ent/docs/reference/Collections/record.mdx → ...s/reference/Schema/Collections/record.mdx
diff --git a/...ontent/docs/reference/Collections/set.mdx → ...docs/reference/Schema/Collections/set.mdx b/...ontent/docs/reference/Collections/set.mdx → ...docs/reference/Schema/Collections/set.mdx
diff --git a/...tent/docs/reference/Collections/tuple.mdx → ...cs/reference/Schema/Collections/tuple.mdx b/...tent/docs/reference/Collections/tuple.mdx → ...cs/reference/Schema/Collections/tuple.mdx
diff --git a/...rc/content/docs/reference/Others/lazy.mdx → ...ent/docs/reference/Schema/Others/lazy.mdx b/...rc/content/docs/reference/Others/lazy.mdx → ...ent/docs/reference/Schema/Others/lazy.mdx
diff --git a/...content/docs/reference/Others/literal.mdx → .../docs/reference/Schema/Others/literal.mdx b/...content/docs/reference/Others/literal.mdx → .../docs/reference/Schema/Others/literal.mdx
diff --git a/...c/content/docs/reference/Others/never.mdx → ...nt/docs/reference/Schema/Others/never.mdx b/...c/content/docs/reference/Others/never.mdx → ...nt/docs/reference/Schema/Others/never.mdx
diff --git a/...c/content/docs/reference/Others/union.mdx → ...nt/docs/reference/Schema/Others/union.mdx b/...c/content/docs/reference/Others/union.mdx → ...nt/docs/reference/Schema/Others/union.mdx
diff --git a/...content/docs/reference/Others/unknown.mdx → .../docs/reference/Schema/Others/unknown.mdx b/...content/docs/reference/Others/unknown.mdx → .../docs/reference/Schema/Others/unknown.mdx
diff --git a/...tent/docs/reference/Primitives/bigint.mdx → ...cs/reference/Schema/Primitives/bigint.mdx b/...tent/docs/reference/Primitives/bigint.mdx → ...cs/reference/Schema/Primitives/bigint.mdx
diff --git a/...ent/docs/reference/Primitives/boolean.mdx → ...s/reference/Schema/Primitives/boolean.mdx b/...ent/docs/reference/Primitives/boolean.mdx → ...s/reference/Schema/Primitives/boolean.mdx
diff --git a/...ontent/docs/reference/Primitives/null.mdx → ...docs/reference/Schema/Primitives/null.mdx b/...ontent/docs/reference/Primitives/null.mdx → ...docs/reference/Schema/Primitives/null.mdx
diff --git a/...tent/docs/reference/Primitives/number.mdx → ...cs/reference/Schema/Primitives/number.mdx b/...tent/docs/reference/Primitives/number.mdx → ...cs/reference/Schema/Primitives/number.mdx
diff --git a/...tent/docs/reference/Primitives/string.mdx → ...cs/reference/Schema/Primitives/string.mdx b/...tent/docs/reference/Primitives/string.mdx → ...cs/reference/Schema/Primitives/string.mdx
diff --git a/...tent/docs/reference/Primitives/symbol.mdx → ...cs/reference/Schema/Primitives/symbol.mdx b/...tent/docs/reference/Primitives/symbol.mdx → ...cs/reference/Schema/Primitives/symbol.mdx
diff --git a/...t/docs/reference/Primitives/undefined.mdx → ...reference/Schema/Primitives/undefined.mdx b/...t/docs/reference/Primitives/undefined.mdx → ...reference/Schema/Primitives/undefined.mdx
diff --git a/...ocs/src/content/docs/reference/schema.mdx → .../content/docs/reference/Schema/common.mdx b/...ocs/src/content/docs/reference/schema.mdx → .../content/docs/reference/Schema/common.mdx
@@ -1,5 +1,5 @@
 ---
-title: "Schema"
+title: "Common"
 sidebar:
     order: 0
 ---
@@ -11,7 +11,8 @@ All schemas contain some common methods.
 ### `parse`
 
 The `parse` method takes a `value` parameter as input. If the `value` conforms to the schema, then the parsed value is
-returned with the appropriate type, otherwise an exception is thrown.
+returned with the appropriate type, otherwise an exception containing a `messages` method is thrown. See the
+[messages](/reference/messages/) reference for details.
 
 ```typescript
 import * as p from '@vbudovski/paseri';
@@ -28,7 +29,8 @@ try {
 ### `safeParse`
 
 The `safeParse` method takes a `value` parameter as input. The result is a discriminated union with a `boolean` member
-`ok`. You can use it to extract the parsed value on success, or a list of issues on failure.
+`ok`. You can use it to extract the parsed value on success or get the error [messages](/reference/messages/) using
+`result.messages()`.
 
 ```typescript
 import * as p from '@vbudovski/paseri';
@@ -38,7 +40,7 @@ const result = schema.safeParse('foo');
 if (result.ok) {
     // Do something with the `result.value`.
 } else {
-    // Do something with the `result.issue`.
+    // Do something with the `result.messages()`.
 }
 ```
 

diff --git a/paseri-docs/src/content/docs/reference/messages.mdx b/paseri-docs/src/content/docs/reference/messages.mdx
@@ -0,0 +1,33 @@
+---
+title: "Messages"
+---
+
+In order to support localised error messages, each parsing error produces a unique error code. This is then looked up in
+the messages object for the selected locale. When calling the `messages` method on either the `safeParse` result or the
+exception thrown from `parse`, you can pass the desired messages object as the parameter. The default messages can be
+found in `locales/en.ts`.
+
+## Contributing new translations
+
+You can copy the definition of the closest language to the one you are targeting as a starting point, if one exists.
+If there isn't a suitable starting point, please create a new file. Be sure to follow the TypeScript type `Translations`
+to ensure all standard messages are handled. The naming of the file should follow the pattern `<language>-<country>`,
+where the language is a 2-letter [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) code, and the
+country is a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. For example, `en-GB` or
+`pt-BR`.
+
+# Custom error codes
+
+You can extend the messages object to add your custom error codes and corresponding translations.
+
+```typescript
+import { en } from '@vbudovski/paseri/locales';
+
+const enCustom = {
+    ...en,
+    ...{
+        foo: 'This is a `foo` error.',
+        bar: 'This is a `bar` error.',
+    }
+} satisfies Translations;
+```
diff --git a/paseri-lib/deno.json b/paseri-lib/deno.json
@@ -1,5 +1,6 @@
 {
   "name": "@vbudovski/paseri",
+  "license": "MIT",
   "version": "0.1.0",
   "exports": "./src/index.ts",
   "imports": {
@@ -9,7 +10,7 @@
     "esbuild": "npm:esbuild",
     "expect-type": "npm:expect-type",
     "fast-check": "npm:fast-check",
-    "type-fest": "npm:type-fest",
+    "type-fest": "npm:type-fest@4.30.0",
     "typescript": "npm:typescript",
     "zod": "npm:zod"
   },
@@ -22,5 +23,8 @@
     "rules": {
       "exclude": ["no-explicit-any", "no-unused-vars"]
     }
+  },
+  "publish": {
+    "include": ["src"]
   }
 }
diff --git a/paseri-lib/src/issue.test.ts b/paseri-lib/src/issue.test.ts