schematox 0.4.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.0.0](https://github.com/incerta/schematox/compare/v0.4.0...v1.0.0)
+
+The module went through major refactoring so it could be ready for production usage:
+
+- [RecordSchema support #34](https://github.com/incerta/schematox/pull/34)
+- [Drop validate/guard feature support #36](https://github.com/incerta/schematox/pull/36)
+- [Pre major release testing architecture and file structure refactoring #38](https://github.com/incerta/schematox/pull/38)
+- [Break down parse logic into smaller functions #39](https://github.com/incerta/schematox/pull/39)
+- [Support unrestricted object schema depth #42](https://github.com/incerta/schematox/pull/42)
+- [Support tuple schema #43](https://github.com/incerta/schematox/pull/43)
+
 ## [0.4.0](https://github.com/incerta/schematox/compare/v0.3.1...v0.4.0)
 
 - [`aa0d95e`](https://github.com/incerta/schematox/commit/aa0d95e30b7784c0ce29317ae808e4ba7950abab) Extend compound structure nesting limit to 12 layers of depth

package/README.md

@@ -1,46 +1,27 @@
-# Schematox
+# schematox
 
-Schematox is a lightweight typesafe schema defined parser/validator. All schemas are JSON compatible.
+Schematox is a lightweight typesafe schema defined parser. All schemas are JSON compatible.
 
-Instead of supporting all possible JS/TS data structures, the library is focusing on fixed set of schema types: string, number, boolean, literal, object, array, union. Each schema can have parameters: optional, nullable, description. Each primitive schema has "brand" parameter as mean of making its subject type [nominal](https://github.com/Microsoft/TypeScript/wiki/FAQ#can-i-make-a-type-alias-nominal). The rest parameters is schema specific range limiters.
+The library is focusing on fixed set of schema types: boolean, literal, number, string, array, object, record, tuple, union. Each schema can have parameters: optional, nullable, description. Each primitive schema has "brand" parameter as mean of making its subject type [nominal](https://github.com/Microsoft/TypeScript/wiki/FAQ#can-i-make-a-type-alias-nominal). The rest parameters is schema specific range limiters.
 
 Library supports static schema definition which means your schemas could be completely independent from schematox. One could use such schemas as source for generation other structures like DB models.
 
-Features:
-
-- Statically defined JSON compatible schema
-- Check defined schema correctness using non generic type "Schema"
-- Programmatically defined schema (struct)
-- Schema subject verification methods:
-  - parse: constructs new object based on the given schema and subject
-  - validate: checks and returns reference to the original schema subject
-  - guard: validates and narrows schema subject type in the current scope
-- Ether-style error handling (no unexpected throws)
-- First-class support for branded primitives (primitive nominal types alias)
-
-Check out [github issues](https://github.com/incerta/schematox/issues) to know what we are planning to support soon.
-
-Currently we on version 0. The public API is mostly defined however few thing left before the first major release:
-
-- Record and tuple schema support
-- Allow parser to replace value before it's validated (similar to [coercing](https://docs.superstructjs.org/guides/03-coercing-data) concept)
-- Clearly defined supported versions of typescript/node
-- Support "deno" runtime and publish package on "deno.land"
-- Have a benchmark that compares library performance with other parsers
-
-The library is small so exploring README.md is enough for understanding its API, checkout limitations/examples and you good to go:
+The library is small so exploring README.md is enough for understanding its API, checkout [examples](#example-for-all-supported-schema-types) and you good to go:
 
 - [Install](#install)
-- [Limitations](#limitations)
+- [Minimal requirements](#minimal-requirements)
+- [Features](#features)
 - [Static schema example](#static-schema-example)
 - [Programmatic schema example](#programmatic-schema-example)
 - [Example for all supported schema types](#example-for-all-supported-schema-types)
-  - [String](#string)
-  - [Number](#number)
   - [Boolean](#boolean)
   - [Literal](#literal)
-  - [Object](#object)
+  - [Number](#number)
+  - [String](#string)
   - [Array](#array)
+  - [Object](#object)
+  - [Record](#record)
+  - [Tuple](#tuple)
   - [Union](#union)
 - [Schema parameters](#schema-parameters)
 - [Error shape](#error-shape)
@@ -51,47 +32,30 @@ The library is small so exploring README.md is enough for understanding its API,
 npm install schematox
 ```
 
-## Limitations
+## Minimal requirements
 
-Currently we support max 12 layers of depth for compound schema type: object, array, union:
+- ECMAScript version: `2018`
+- TypeScript version: `5.3.2`
 
-```typescript
-const schema = object({
-  1: object({
-    2: object({
-      3: object({
-        4: object({
-          5: object({
-            6: object({
-              7: object({
-                8: object({
-                  9: object({
-                    10: object({
-                      11: object({ 12: object({ x: string() }) }),
-                    }),
-                  }),
-                }),
-              }),
-            }),
-          }),
-        }),
-      }),
-    }),
-  }),
-})
-```
+## Features
+
+- Statically defined JSON compatible schema
+- Programmatically defined schema (struct)
+- Check defined schema correctness using non generic type "Schema"
+- Ether-style error handling (no unexpected throws)
+- First-class support for branded primitives (primitive nominal types alias)
+- Construct type requirement for schema itself using exposed type generics
 
-Cryptic typescript type error will be raised if the limit is exceeded.
 
 ## Static schema example
 
 Statically defined schema:
 
 ```typescript
-import { parse, validate, guard } from 'schematox'
-import type { Schema } from 'schematox'
+import { parse } from 'schematox'
+import type { Schema, Infer } from 'schematox'
 
-export const userSchema = {
+export const schema = {
   type: 'object',
   of: {
     id: {
@@ -102,31 +66,27 @@ export const userSchema = {
   },
 } as const satisfies Schema
 
-const subject = {
-  id: '1' as SubjectType<typeof userSchema.id>,
-  name: 'John',
-} as unknown
+type User = Infer<typeof schema>
+  // ^?  { id: string & { __idFor: 'User' }, name: string }
 
+const subject = { id: '1'  name: 'John' }
 const parsed = parse(userSchema, subject)
+   // ^? ParseResult<User>
 
-if (parsed.left) {
-  throw Error('Not expected')
-}
-
-console.log(parsed.right) // { id: '1', name: 'John' }
+parsed.error
+    // ^? InvalidSubject[] | undefined
 
-const validated = validate(userSchema, subject)
+parsed.data
+    // ^?  User | undefined
 
-if (validated.left) {
-  throw Error('Not expected')
+if (parsed.success === false) {
+  parsed.error
+      // ^? InvalidSubject[]
+  throw Error('Parsing error')
 }
 
-console.log(validated.right) // { id: '1', name: 'John' }
-
-if (guard(userSchema, subject)) {
-  // { id: string & { __idFor: 'User' }; name: string }
-  subject
-}
+parsed.data
+    // ^? User
 ```
 
 ## Programmatic schema example
@@ -135,48 +95,80 @@ Same schema but defined programmatically:
 
 ```typescript
 import { object, string } from 'schematox'
-import type { SubjectType } from 'schematox'
+import type { Infer } from 'schematox'
 
 const struct = object({
   id: string().brand('idFor', 'User'),
   name: string(),
 })
 
-const subject = { id: '1', name: 'John' } as unknown
+type User = Infer<typeof struct>
+  // ^?  { id: string & { __idFor: 'User' }, name: string }
 
+const subject = { id: '1', name: 'John' }
 const parsed = struct.parse(subject)
+   // ^?  ParseResult<User>
+
+parsed.error
+    // ^?  InvalidSubject[] | undefined
 
-if (parsed.left) {
-  throw Error('Not expected')
+parsed.data
+    // ^?  User | undefined
+
+if (parsed.success === false) {
+  parsed.error
+      // ^? InvalidSubject[]
+  throw Error('Parsing error')
 }
 
-console.log(parsed.right) // { id: '1', name: 'John' }
+parsed.data
+    // ^? User
+```
 
-const validated = struct.validate(subject)
+All programmatically defined schemas are the same as static, one just needs to access it through `__schema` key.
+A statically defined schema can be transformed to a struct using the `makeStruct` utility function and can have custom props.
 
-if (validated.left) {
-  throw Error('Not expected')
-}
+## Transform static schema into struct
 
-console.log(validated.right) // { id: '1', name: 'John' }
+```typescript
+import { makeStruct } from 'schematox'
+import type { Schema } from 'schematox'
 
-if (struct.guard(subject)) {
-  // { id: string & { __idFor: 'User' }; name: string }
-  subject
-}
+const schema = { type: 'string' } as const satisfies Schema
+const string = makeStruct(schema)
 ```
 
-All programmatically defined schemas are the same as static, one just needs to access it through `__schema` key. We can mix static/programmatic schemas either accessing it through `__schema` or wrap it by `{ __schema: T }` if consumer is programmatic schema.
-
 ## Example for all supported schema types
 
 We distinguish two main categories of schema units:
 
-- primitive: string, number, boolean, literal
-- compound: object, array, union
+- primitive: boolean, literal, number, boolean
+- compound: array, object, record, union
 
 Any schema share optional/nullable/description parameters. Any compound schema could have any other schema type as its member including itself. Any primitive schema can have "brand" parameter.
 
+### Boolean
+
+```typescript
+const schema = {
+  type: 'boolean',
+  optional: true,
+  nullable: true,
+  brand: ['x', 'y'],
+  description: 'x',
+} as const satisfies Schema
+
+const struct = boolean() //
+  .optional()
+  .nullable()
+  .brand('x', 'y')
+  .description('x')
+
+// (boolean & { __x: 'y' }) | undefined | null
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
+```
+
 ### String
 
 ```typescript
@@ -199,86 +191,93 @@ const struct = string()
   .description('x')
 
 // (string & { __x: 'y' }) | undefined | null
-type FromSchema = SubjectType<typeof schema>
-type FromStruct = SubjectType<typeof struct>
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
 ```
 
-### Number
+### Literal
+
+Could be string/number/boolean literal.
 
 ```typescript
 const schema = {
-  type: 'number',
+  type: 'literal',
+  of: 'x',
   optional: true,
   nullable: true,
   brand: ['x', 'y'],
-  min: 1,
-  max: 2,
   description: 'x',
 } as const satisfies Schema
 
-const struct = number()
+const struct = literal('x') //
   .optional()
   .nullable()
   .brand('x', 'y')
-  .min(1)
-  .max(2)
   .description('x')
 
-// (number & { __x: 'y' }) | undefined | null
-type FromSchema = SubjectType<typeof schema>
-type FromStruct = SubjectType<typeof struct>
-//
+// ('x' & { __x: 'y' }) | undefined | null
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
 ```
 
-### Boolean
+### Number
+
+We accept only finite numbers as valid number schema subjects.
 
 ```typescript
 const schema = {
-  type: 'boolean',
+  type: 'number',
   optional: true,
   nullable: true,
   brand: ['x', 'y'],
+  min: 1,
+  max: 2,
   description: 'x',
 } as const satisfies Schema
 
-const struct = boolean() //
+const struct = number()
   .optional()
   .nullable()
   .brand('x', 'y')
+  .min(1)
+  .max(2)
   .description('x')
 
-// (boolean & { __x: 'y' }) | undefined | null
-type FromSchema = SubjectType<typeof schema>
-type FromStruct = SubjectType<typeof struct>
+// (number & { __x: 'y' }) | undefined | null
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
+//
 ```
 
-### Literal
-
-Could be string/number/boolean literal
+### Array
 
 ```typescript
 const schema = {
-  type: 'literal',
-  of: 'x',
+  type: 'array',
+  of: { type: 'string' },
   optional: true,
-  nullable: true,
-  brand: ['x', 'y'],
+  minLength: 1,
+  maxLength: 1000,
   description: 'x',
 } as const satisfies Schema
 
-const struct = literal('x') //
+const struct = array(string())
   .optional()
   .nullable()
-  .brand('x', 'y')
+  .minLength(1)
+  .maxLength(1000)
   .description('x')
 
-// ('x' & { __x: 'y' }) | undefined | null
-type FromSchema = SubjectType<typeof schema>
-type FromStruct = SubjectType<typeof struct>
+// string[] | undefined | null
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
 ```
 
 ### Object
 
+Extra properties in the parsed subject that are not specified in the `object` schema will not cause an error and will be skipped.
+This is a deliberate decision that allows client schemas to remain functional whenever the API is extended.
+
 ```typescript
 const schema = {
   type: 'object',
@@ -300,36 +299,60 @@ const struct = object({
   .description('x')
 
 // { x: string; y: number } | undefined | null
-type FromSchema = SubjectType<typeof schema>
-type FromStruct = SubjectType<typeof struct>
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
 ```
 
-### Array
+### Record
+
+Undefined record entries are skipped in parsed results. If a key exists, it means a value is also present.
 
 ```typescript
 const schema = {
-  type: 'array',
-  of: { type: 'string' },
+  type: 'record',
+  // key property is optional
+  key: { type: 'string', brand: ['idFor', 'user'] },
+  of: { type: 'number' },
   optional: true,
-  minLength: 1,
-  maxLength: 1000,
+  nullable: true,
   description: 'x',
 } as const satisfies Schema
 
-const struct = array(string())
+const userId = string().brand('idFor', 'user')
+
+// second argument is optional
+const struct = object(number(), userId).optional().nullable().description('x')
+
+// Record<string & { __brand: ['idFor', 'user'] }, number | undefined>  | null | undefined
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
+```
+
+### Tuple
+
+```typescript
+const schema = {
+  type: 'tuple',
+  of: [{ type: 'string' }, { type: 'number' }],
+  optional: true,
+  nullable: true,
+  description: 'x',
+} as const satisfies Schema
+
+const struct = tuple([string(), number()])
   .optional()
   .nullable()
-  .minLength(1)
-  .maxLength(1000)
   .description('x')
 
-// string[] | undefined | null
-type FromSchema = SubjectType<typeof schema>
-type FromStruct = SubjectType<typeof struct>
+// [string, number] | undefined | null
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
 ```
 
 ### Union
 
+Be careful with object unions that do not have a unique discriminant. The parser will check the subject in the order that is specified in the union array and accept the first match.
+
 ```typescript
 const schema = {
   type: 'union',
@@ -345,24 +368,13 @@ const struct = union([string(), number()])
   .description('x')
 
 // string | number | undefined | null
-type FromSchema = SubjectType<typeof schema>
-type FromStruct = SubjectType<typeof struct>
+type FromSchema = Infer<typeof schema>
+type FromStruct = Infer<typeof struct>
 ```
 
 ## Schema parameters
 
 - `optional?: boolean` –  unionize with `undefined`: `{ type: 'string', optinoal: true }` result in `string | undefined`
-
-In the context of the object, optional values will be treated as optional properties:
-
-```typescript
-const struct = object({ x: string().optional() })
-
-type ExpectedSubjectType = {
-  x?: string | undefined
-}
-```
-
 - `nullable?: boolean` – unionize with `null`: `{ type: 'string', nullable: true }` result in `string | null`
 - `brand?: [string, string]` – make primitive type nominal "['idFor', 'User'] -> T & { \_\_idFor: 'User' }"
 - `minLength/maxLength/min/max` – schema type dependent limiting characteristics
@@ -388,22 +400,24 @@ const struct = object({
 const result = struct.parse({ x: { y: [{ z: 0 }] } })
 ```
 
-The `result.left` shape is:
+The `result.error` shape is:
 
 ```json
 [
   {
     "code": "INVALID_TYPE",
+    "path": ["x", "y", 0, "z"]
     "schema": { "type": "string" },
     "subject": 0,
-    "path": ["x", "y", 0, "z"]
   }
 ]
 ```
 
-It's always an array with at least one entry. Each entry includes:
+It's always an array of `InvalidSubject` entries, each has the following properties:
 
-- `code`: Specifies either `INVALID_TYPE` (when schema subject or default value don't meet schema type specifications), or `INVALID_RANGE` (when `min/max` or `minLength/maxLength` schema requirements aren't met).
-- `schema`: The specific section of `schema` where the invalid value is found.
-- `subject`: The specific part of the validated subject where the invalid value exists.
-- `path`: Traces the route from the root to the error subject, with strings as keys and numbers as array indexes.
+- `code`:
+  - `INVALID_TYPE`: schema subject or default value don't meet schema type specifications
+  - `INVALID_RANGE`: `min/max` or `minLength/maxLength` schema requirements aren't met
+- `schema`: the specific section of `schema` where the invalid value is found.
+- `subject`: the specific part of the validated subject where the invalid value exists.
+- `path`: traces the route from the root to the error subject, with strings as keys and numbers as array indexes.

package/package.json

@@ -1,14 +1,38 @@
 {
   "name": "schematox",
-  "version": "0.4.1",
-  "description": "Define JSON compatible schema statically/programmatically and parse/validate its subject with typesafety",
+  "version": "1.0.0",
+  "scripts": {
+    "prepublishOnly": "bash release-check.sh",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "formatter:fix": "prettier --write .",
+    "formatter:check": "prettier --check . || (echo \"ERROR: use `npm run formatter:fix`\" && exit 1)",
+    "ts": "tsc --noEmit",
+    "check": "npm run formatter:check && npm run ts && npm run test & npm run test:coverage",
+    "morph": "jiti src/tests/fold-morph.ts && npm run formatter:fix",
+    "version:patch": "npm run check && npm version patch",
+    "version:minor": "npm run check && npm version minor",
+    "version:major": "npm run check && npm version major"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.3.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.1",
+    "jest": "^29.5.0",
+    "prettier": "^3.1.1",
+    "ts-jest": "^29.1.0",
+    "ts-morph": "^26.0.0",
+    "typescript": "^5.3.2"
+  },
+  "description": "Define JSON compatible schema statically/programmatically and parse its subject with typesafety",
   "author": "Kanstantsin Mazur",
   "license": "MIT",
   "keywords": [
     "typescript",
     "schema",
     "parser",
-    "validator",
     "typeguard",
     "static schema definition",
     "programmatic schema definition",
@@ -17,32 +41,10 @@
     "either style error handling",
     "lightweight"
   ],
-  "repository": "git://github.com/incerta/schematox.git",
-  "main": "dist/index.js",
-  "types": "dist/index.ts",
-  "scripts": {
-    "prepare": "husky install",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "prettify": "prettier --write .",
-    "prettier-check": "prettier --check . || (echo \"Please use 'npm run prettify' to fix the issue\" && exit 1)",
-    "lint": "eslint .",
-    "type-check": "tsc --noEmit",
-    "build": "tsc && rm -rf dist/types && cp -r src/types dist && rm dist/index.d.ts && cp src/index.ts dist",
-    "quality-check": "npm run prettier-check && npm run lint && npm run type-check && npm run test",
-    "check-n-build": "npm run quality-check && npm run build",
-    "publish-patch": "npm run check-n-build && npm version patch && npm run check-n-build && npm publish",
-    "publish-minor": "npm run check-n-build && npm version minor && npm run check-n-build && npm publish"
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/incerta/schematox.git"
   },
-  "devDependencies": {
-    "@types/jest": "^29.5.1",
-    "@typescript-eslint/eslint-plugin": "^5.59.5",
-    "@typescript-eslint/parser": "^5.59.5",
-    "eslint": "^8.40.0",
-    "husky": "^8.0.0",
-    "jest": "^29.5.0",
-    "prettier": "^3.1.1",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.0.4"
-  }
+  "main": "src/index.ts",
+  "types": "src/index.ts"
 }

package/src/constants.ts

@@ -0,0 +1,18 @@
+export const ERROR_CODE = {
+  invalidType: 'INVALID_TYPE',
+  invalidRange: 'INVALID_RANGE',
+} as const
+
+// prettier-ignore
+export const PARAMS_BY_SCHEMA_TYPE = {
+  boolean:  new Set(['optional', 'nullable', 'brand', 'description'] as const),
+  literal:  new Set(['optional', 'nullable', 'brand', 'description'] as const),
+  number:   new Set(['optional', 'nullable', 'brand', 'description', 'min', 'max'] as const),
+  string:   new Set(['optional', 'nullable', 'brand', 'description', 'minLength', 'maxLength'] as const),
+  //
+  array:    new Set(['optional', 'nullable', 'description', 'minLength', 'maxLength'] as const),
+  object:   new Set(['optional', 'nullable', 'description'] as const),
+  record:   new Set(['optional', 'nullable', 'description'] as const),
+  tuple:    new Set(['optional', 'nullable', 'description'] as const),
+  union:    new Set(['optional', 'nullable', 'description'] as const),
+} as const