schematox 0.0.6 → 0.1.2

package/README.md

@@ -1,46 +1,68 @@
-# SchematoX
+# Schematox
 
-SchmatoX is a lightweight library for creating JSON compatible schemas. The subject of the schema can be parsed or validated by the library in a type-safe manner. Instead of focusing on supporting all possible JS/TS data structures, we provide a set of constraints that help reduce the complexity of communication between different JS tools and runtimes.
+Schematox is a lightweight typesafe schema defined parser/validator. All schemas are JSON compatible.
 
-## Pros
+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 statically defined JSON compatible schema
-- Check defined schema correctness using non generic type `Schema`
-- Programmatically defined schemas supported as mean of creation statically defined schema
-- Clear separation of concerns for validating and parsing logic:
-  - Parser is used for dealing with an outer uknnown interface
-  - Validator is used for dealing with an internal known interface
-- Schematox uses an Ether-style error handling
-- We offer first-class support for branded base schema primitive types
-- We have zero dependencies. The runtime code logic is small and easy to grasp, consisting of just a couple of functions. Most of the library code is tests and types.
+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.
 
-Essentially, to define a schema, one doesn't need to import any functions from our library, only the `as const satisfies Schema` statement. This approach does come with a few limitations. The first is `stringUnion` and `numberUnion` schema default values are not constrained by the defined union choices, only the primitive type. We might fix this issue later, but for now, we prioritize this over the case when `default` extends union choice by its definition.
+Features:
 
-A second limitation is the depth of the compound schema data structure. Currently, we support 7 layers of depth. It's easy to increase this number, but because of the exponential nature of stored type variants in memory, we want to determine how much RAM each next layer will use before increasing it.
+- 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)
 
-It's crucial to separate parsing/validation logic from the schema itself. Libraries like `superstract` or `zod` mix these two elements. While that's handy for starters, it reduces our ability to create independent parsers/validators. The same goes for building infrastructure based on top of these great alternatives. As mentioned, our schemas are just JSON compatible objects, which can be completely independent from our library.
+Check out [github issues](https://github.com/incerta/schematox/issues) to know what we are planning to support soon.
 
-## Cons
+Currently we on version 0. The public API is mostly defined however few thing left before the first major release:
 
-- The library is not ready for production yet, the version is 0 and public API might be changed
-- Currently we support only 7 layers of compound structure depth but most likely it will be higher soon
-- We do not support records, discriminated unions, object unions, array unions, intersections, functions, NaN, Infinity and other not JSON compatible structures
-- Null value is acceptable by the parser but will be treated as undefined and transformed to undefined
-- Null value is not acceptable by the validator
+- 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
 
-Check out [github issues](https://github.com/incerta/schematox/issues) of the project to know what we are planning to support soon.
+The library is small so exploring README.md is enough for understanding its API, checkout limitations/examples and you good to go:
 
-## Installation
+- [Install](#install)
+- [Limitations](#limitations)
+- [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)
+  - [Array](#array)
+  - [Union](#union)
+- [Schema parameters](#schema-parameters)
+- [Error shape](#error-shape)
+
+## Install
 
 ```sh
 npm install schematox
 ```
 
-## Example
+## Limitations
+
+Currently we support max 7 layers of depth for compound schema type: object, array, union.
+
+Because of this we can check structural correctness of the statically defined schema using non generic type `Schema`. Important detail is that `union` schema type is also compound type so each nested definition counts as +1 layer of depth.
+
+## Static schema example
 
 Statically defined schema:
 
 ```typescript
+import { parse, validate, guard } from 'schematox'
 import type { Schema } from 'schematox'
 
 export const userSchema = {
@@ -50,266 +72,283 @@ export const userSchema = {
       type: 'string',
       brand: ['idFor', 'User'],
     },
-    email: {
-      type: 'string',
-      optional: true,
-      brand: ['format', 'email'],
-    },
-    updatedAt: {
-      type: 'number',
-      brand: ['format', 'msUnixTimestamp'],
-    },
-    canRead: {
-      type: 'array',
-      of: {
-        type: 'string',
-        brand: ['idFor', 'User'],
-      },
-      minLength: 1,
-    },
-    canWrite: {
-      type: 'array',
-      of: {
-        type: 'string',
-        brand: ['idFor', 'User'],
-      },
-      minLength: 1,
-    },
-    bio: { type: 'string', optional: true },
+    name: { type: 'string' },
   },
 } as const satisfies Schema
-```
 
-Same schema but defined programmatically:
+const subject = {
+  id: '1' as SubjectType<typeof userSchema.id>,
+  name: 'John',
+} as unknown
 
-```typescript
-import { object, string, number, boolean, array } from 'schematox'
-
-const userIdX = string().brand('idFor', 'User')
-const emailX = string().brand('format', 'email')
-const msUnixTimestampX = number().brand('format', 'msUnixTimestamp')
-
-export const userSchema = object({
-  id: userIdX,
-  email: emailX,
-  updatedAt: updatedAtX,
-  canRead: array(userId),
-  canWrite: array(userId),
-  bio: string().optional(true),
-})
-```
+const parsed = parse(userSchema, subject)
 
-Parse/validate:
+if (parsed.error) {
+  throw Error('Not expected')
+}
 
-```typescript
-import { parse, validate, x } from 'schematox'
-import { userSchema, userId, emailX, msUnixTimestampX } './schema'
+console.log(parsed.data) // { id: '1', name: 'John' }
 
-import type { XParse } from 'schematox'
+const validated = validate(userSchema, subject)
 
-type UserId = XParse<typeof userId>
-type Email = XParse<typeof emailX>
-type MsUnixTimestamp = XParse<typeof msUnixTimestamp>
+if (validated.error) {
+  throw Error('Not expected')
+}
 
-const adminUserId = '1' as UserId
+console.log(validated.data) // { id: '1', name: 'John' }
 
-const schemaSubject = {
-  id: adminUserId,
-  email: 'john@dow.com' as Email,
-  updatedAt: Date.now() as MsUnixTimestamp,
-  canRead: [userId],
-  canWrite: [userId],
-  bio: undefined,
+if (guard(userSchema, subject)) {
+  // { id: string & { __idFor: 'User' }; name: string }
+  subject
 }
+```
 
-const parsed = parse(userSchema, schemaSubject)
+## Programmatic schema example
 
-// We need a type guard before accessing the prased.data
-if (parsed.error) {
-  throw Error('Not expected')
-}
+Same schema but defined programmatically:
+
+```typescript
+import { object, string } from 'schematox'
+import type { SubjectType } from 'schematox'
+
+const struct = object({
+  id: string().brand('idFor', 'User'),
+  name: string(),
+})
 
-console.log(parsed.data)
+const subject = { id: '1', name: 'John' } as unknown
 
-const validated = validate(userSchema, schemaSubject)
+const parsed = struct.parse(subject)
 
-// We need a type guard before accessing the validated.data
 if (parsed.error) {
   throw Error('Not expected')
 }
 
-console.log(validated.data)
+console.log(parsed.data) // { id: '1', name: 'John' }
 
-/* Another way of doing the same */
+const validated = struct.validate(subject)
 
-const userSchemaX = x(userSchema)
-
-const parsedByX = userSchemaX.parse(schemaSubject)
-const validatedByX = userSchemaX.validate(schemaSubject)
-```
+if (validated.error) {
+  throw Error('Not expected')
+}
 
-Result type of `parsedByX.data` or `validatedByX.data`
+console.log(validated.data) // { id: '1', name: 'John' }
 
-```typescript
-type Data = {
-  id: string & { __idFor: 'User' }
-  email: string & { __format: 'email' }
-  updatedAt: number & { __format: 'msUnixTimestamp' }
-  canRead: Array<string & { __idFor: 'User' }>
-  canWrite: Array<string & { __idFor: 'User' }>
+if (struct.guard(subject)) {
+  // { id: string & { __idFor: 'User' }; name: string }
+  subject
 }
 ```
 
-## All supported data types
+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.
 
-```typescript
-import {
-  array,
-  object,
-  string,
-  number,
-  boolean,
-  stringUnion,
-  numberUnion,
-} from 'schematox'
+## Example for all supported schema types
 
-import type { Schema } from 'schematox'
+We distinguish two main categories of schema units:
+
+- primitive: string, number, boolean, literal
+- compound: object, array, union
 
-/* Base types */
+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.
 
-// string
+### String
 
-const staticString = {
+```typescript
+const schema = {
   type: 'string',
   optional: true,
-  default: 'x',
+  nullable: true,
   brand: ['x', 'y'],
   minLength: 1,
-  maxLength: 1,
+  maxLength: 2,
   description: 'x',
 } as const satisfies Schema
 
-const programmaticString = string()
+const struct = string()
   .optional()
-  .default('x')
-  .minLength(1)
-  .maxLength(1)
+  .nullable()
   .brand('x', 'y')
-  .description('y')
+  .minLength(1)
+  .maxLength(2)
+  .description('x')
 
-// number
+// (string & { __x: 'y' }) | undefined | null
+type FromSchema = SubjectType<typeof schema>
+type FromStruct = SubjectType<typeof struct>
+```
 
-const staticNumber = {
+### Number
+
+```typescript
+const schema = {
   type: 'number',
   optional: true,
-  default: 1,
+  nullable: true,
   brand: ['x', 'y'],
   min: 1,
-  max: 1,
+  max: 2,
   description: 'x',
 } as const satisfies Schema
 
-const programmaticNumber = number()
+const struct = number()
   .optional()
-  .default(1)
-  .min(1)
-  .max(1)
+  .nullable()
   .brand('x', 'y')
-  .description('y')
+  .min(1)
+  .max(2)
+  .description('x')
+
+// (number & { __x: 'y' }) | undefined | null
+type FromSchema = SubjectType<typeof schema>
+type FromStruct = SubjectType<typeof struct>
+//
+```
 
-// boolean
+### Boolean
 
-const staticBoolean = {
+```typescript
+const schema = {
   type: 'boolean',
   optional: true,
-  default: false,
+  nullable: true,
   brand: ['x', 'y'],
   description: 'x',
 } as const satisfies Schema
 
-const programmaticBoolean = boolean()
+const struct = boolean() //
   .optional()
-  .default(false)
+  .nullable()
   .brand('x', 'y')
-  .description('y')
+  .description('x')
 
-// stringUnion
-
-const staticStringUnion = {
-  type: 'stringUnion',
-  of: ['x', 'y', 'z'],
-  optional: true,
-  brand: ['x', 'y'],
-  description: 'x',
-} as const satisfies Schema
+// (boolean & { __x: 'y' }) | undefined | null
+type FromSchema = SubjectType<typeof schema>
+type FromStruct = SubjectType<typeof struct>
+```
 
-const programmaticStringUnion = stringUnion('x', 'y', 'z')
-  .optional()
-  .brand('x', 'y')
-  .description('y')
+### Literal
 
-// stringUnion
+Could be string/number/boolean literal
 
-const staticNumberUnion = {
-  type: 'numberUnion',
-  of: [0, 1, 2],
+```typescript
+const schema = {
+  type: 'literal',
+  of: 'x',
   optional: true,
+  nullable: true,
   brand: ['x', 'y'],
   description: 'x',
 } as const satisfies Schema
 
-const programmaticNumberUnion = numberUnion(0, 1, 2)
+const struct = literal('x') //
   .optional()
+  .nullable()
   .brand('x', 'y')
-  .description('y')
+  .description('x')
 
-/* Compound schema */
+// ('x' & { __x: 'y' }) | undefined | null
+type FromSchema = SubjectType<typeof schema>
+type FromStruct = SubjectType<typeof struct>
+```
 
-// object
+### Object
 
-const staticObject = {
+```typescript
+const schema = {
   type: 'object',
   of: {
-    x: 'string',
-    y: 'number?',
+    x: { type: 'string' },
+    y: { type: 'number' },
   },
+  optional: true,
+  nullable: true,
+  description: 'x',
 } as const satisfies Schema
 
-const programmaticObject = object({
+const struct = object({
   x: string(),
-  y: number().optional(),
+  y: number(),
 })
+  .optional()
+  .nullable()
+  .description('x')
 
-// array
+// { x: string; y: number } | undefined | null
+type FromSchema = SubjectType<typeof schema>
+type FromStruct = SubjectType<typeof struct>
+```
+
+### Array
 
-const staticArray = {
+```typescript
+const schema = {
   type: 'array',
-  of: 'string',
+  of: { type: 'string' },
+  optional: true,
+  minLength: 1,
+  maxLength: 1000,
+  description: 'x',
 } as const satisfies Schema
 
-const programmaticArray = array(string())
+const struct = array(string())
+  .optional()
+  .nullable()
+  .minLength(1)
+  .maxLength(1000)
+  .description('x')
+
+// string[] | undefined | null
+type FromSchema = SubjectType<typeof schema>
+type FromStruct = SubjectType<typeof struct>
 ```
 
-## Validate/parse InvalidSubject error shape
+### Union
+
+```typescript
+const schema = {
+  type: 'union',
+  of: [{ type: 'string' }, { type: 'number' }],
+  optional: true,
+  nullable: true,
+  description: 'x',
+} as const satisfies Schema
+
+const struct = union([string(), number()])
+  .optional()
+  .nullable()
+  .description('x')
+
+// string | number | undefined | null
+type FromSchema = SubjectType<typeof schema>
+type FromStruct = SubjectType<typeof struct>
+```
+
+## Schema parameters
+
+- `optional?: boolean` – does `undefined` is valid value
+- `nullable?: boolean` – does `null` is valid value
+- `brand?: [string, string]` – make primitive type nominal "['idFor', 'User'] -> T & { \_\_idFor: 'User' }"
+- `minLength/maxLength/min/max` – schema type dependent limiting characteristics
+- `description?: string` – description of the particular schema property which can be used to provide more detailed information for the user/developer on validation/parse error
+
+## Error shape
 
 Nested schema example. Subject `0` is invalid, should be a `string`:
 
 ```typescript
-import { x, object, array, string } from 'schematox'
-
-const schemaX = x(
-  object({
-    x: object({
-      y: array(
-        object({
-          z: string(),
-        })
-      ),
-    }),
-  })
-)
-
-const result = schemaX.parse({ x: { y: [{ z: 0 }] } })
+import { object, array, string } from 'schematox'
+
+const struct = object({
+  x: object({
+    y: array(
+      object({
+        z: string(),
+      })
+    ),
+  }),
+})
+
+const result = struct.parse({ x: { y: [{ z: 0 }] } })
 ```
 
 The `result.error` shape is:
@@ -331,76 +370,3 @@ It's always an array with at least one entry. Each entry includes:
 - `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.
-
-## Parse and validate differences
-
-The parser returns `data` as new object/primitive without references to the parsed subject. Parser manages the `null` value as `undefined` and subsequently replaces it with `undefined`. It also swaps `optional` values with the `default` value from schema. One can infer schema parsed subject type by using `XParsed<typeof schema>` generic.
-
-The validator on the other hand returns the evaluated subject itself and not applying any mutation/transformation to it. The validator should be used in exceptional cases when we known subject type but not sure that it actually correct. One can infer schema validated subject type by using `XValidated<typeof schema>` generic.
-
-So the difference between `XParsed` and `XValidated` is just about handling `default` schema value. `XParsed` narrows optional schema subject type with default value in the way that it will not be optional, because optional `undefined` and `null` values will be replaced by the `default`. `XValidated` just ignores `default` schema value.
-
-Examples:
-
-```typescript
-const optionalStrX = x({ type: 'string', optional: true } as const)
-
-/* Parser doesn't check subject type */
-
-expect(optionalStrX.parse(0).error).toStrictEqual([
-  {
-    code: 'INVALID_TYPE',
-    schema: { type: 'string', optional: true },
-    subject: 0,
-    path: [],
-  },
-])
-
-/* Validator does */
-
-// @ts-expect-error 'number' is not 'string'
-expect(optionalStrX.validate(0).error).toStrictEqual([
-  {
-    code: 'INVALID_TYPE',
-    schema: { type: 'string', optional: true },
-    subject: 0,
-    path: [],
-  },
-])
-
-/* Parser treats `null` as `undefined` */
-
-expect(optionalStrX.parse(null).data).toBe(undefined)
-expect(optionalStrX.parse(null).error).toBe(undefined)
-
-/* Validator is not */
-
-// @ts-expect-error 'null' is not 'string | undefined'
-expect(optionalStrX.validate(null).error).toStrictEqual([
-  {
-    code: 'INVALID_TYPE',
-    schema: { type: 'string', optional: true },
-    subject: null,
-    path: [],
-  },
-])
-
-const defaultedStrX = x({ type: 'string', optional: true, default: 'y' })
-
-/* Parser uses `default` value on `null` or `undefined` subject  */
-
-expect(defaultedStrX.parse(null).data).toBe('y')
-expect(defaultedStrX.parse(undefined).data).toBe('y')
-
-/* Validator ignores default value */
-
-expect(defaultedStrX.validate(undefined).data).toBe(undefined)
-
-/* Parser returning new object */
-
-expect(arrX.parse(subject).data === subject).toBe(false)
-
-/* Validator keeps the subject reference */
-
-expect(arrX.validate(subject).data === subject).toBe(true)
-```

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const PARAMS_BY_SCHEMA_TYPE: {
+    readonly string: Set<"optional" | "nullable" | "brand" | "description" | "minLength" | "maxLength">;
+    readonly number: Set<"optional" | "nullable" | "brand" | "description" | "min" | "max">;
+    readonly boolean: Set<"optional" | "nullable" | "brand" | "description">;
+    readonly literal: Set<"optional" | "nullable" | "brand" | "description">;
+    readonly object: Set<"optional" | "nullable" | "description">;
+    readonly array: Set<"optional" | "nullable" | "description" | "minLength" | "maxLength">;
+    readonly union: Set<string>;
+};

package/dist/constants.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARAMS_BY_SCHEMA_TYPE = void 0;
+exports.PARAMS_BY_SCHEMA_TYPE = {
+    string: new Set([
+        'optional',
+        'nullable',
+        'brand',
+        'description',
+        'minLength',
+        'maxLength',
+    ]),
+    number: new Set([
+        'optional',
+        'nullable',
+        'brand',
+        'description',
+        'min',
+        'max',
+    ]),
+    boolean: new Set(['optional', 'nullable', 'brand', 'description']),
+    literal: new Set(['optional', 'nullable', 'brand', 'description']),
+    object: new Set(['optional', 'nullable', 'description']),
+    array: new Set([
+        'optional',
+        'nullable',
+        'description',
+        'minLength',
+        'maxLength',
+    ]),
+    union: new Set(['optional', 'nullable', 'description']),
+};