schematox 1.0.0 → 1.1.0-alpha

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.0.1](https://github.com/incerta/schematox/compare/v1.0.0...v1.0.1)
+
+- [FIX: struct brand assignment second argument type restriction #44](https://github.com/incerta/schematox/pull/44)
+
 ## [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:

package/README.md

@@ -1,4 +1,4 @@
-# schematox
+# Schematox
 
 Schematox is a lightweight typesafe schema defined parser. All schemas are JSON compatible.
 
@@ -6,25 +6,28 @@ The library is focusing on fixed set of schema types: boolean, literal, number,
 
 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.
 
-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:
+The library is small so exploring README.md is enough for understanding its API, checkout [examples](#quick-start) and you good to go:
 
 - [Install](#install)
-- [Minimal requirements](#minimal-requirements)
+- [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)
+- [Quick Start](#quick-start)
+  - [Static Schema](#static-schema)
+  - [Struct](#struct)
+  - [Construct](#construct)
+- [Primitive Schema](#primitive-schema)
   - [Boolean](#boolean)
   - [Literal](#literal)
   - [Number](#number)
   - [String](#string)
+- [Compound Schema](#compound-schema)
   - [Array](#array)
   - [Object](#object)
   - [Record](#record)
   - [Tuple](#tuple)
   - [Union](#union)
-- [Schema parameters](#schema-parameters)
-- [Error shape](#error-shape)
+- [Schema Parameters](#schema-parameters)
+- [Error Shape](#error-shape)
 
 ## Install
 
@@ -32,24 +35,35 @@ The library is small so exploring README.md is enough for understanding its API,
 npm install schematox
 ```
 
-## Minimal requirements
+## Minimal Requirements
 
 - ECMAScript version: `2018`
 - TypeScript version: `5.3.2`
 
 ## Features
 
-- Statically defined JSON compatible schema
-- Programmatically defined schema (struct)
-- Check defined schema correctness using non generic type "Schema"
+- Statically defined **JSON** compatible schema
+- Programmatically defined schema (**struct**, **construct**)
+- 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
+- Support the [standard schema](https://standardschema.dev) - a common interface for TypeScript validation libraries
 
+## Quick Start
 
-## Static schema example
+One can use three ways of schema definition using `schematox` library:
 
-Statically defined schema:
+- **Static**: a JSON-compatible object that structurally conforms to the `Schema` type
+- **Struct**: is commonly accepted way of schema definition, as seen in [zod](https://github.com/colinhacks/zod) or [superstruct](https://github.com/ianstormtaylor/superstruct)
+- **Construct**: use `makeStruct` function to get `struct` from `static` schema
+
+All **programmatically defined** (`struct`, `construct`) schemas are eventually based on `static`, which could be accessed by `__schema` key. All schemas must be immutable constants and should not be mutated by the user. Each application of `struct` parameters related to schema update will create shallow copy of the original schema.
+
+### Static schema
+
+A JSON-compatible object that structurally conforms to the `Schema` type.
+The `satisfies Schema` check is optional, structurally valid schema will be accepted by the parser.
 
 ```typescript
 import { parse } from 'schematox'
@@ -89,9 +103,9 @@ parsed.data
     // ^? User
 ```
 
-## Programmatic schema example
+### Struct
 
-Same schema but defined programmatically:
+Is commonly accepted way of schema, as seen in [zod](https://github.com/colinhacks/zod) or [superstruct](https://github.com/ianstormtaylor/superstruct) library:
 
 ```typescript
 import { object, string } from 'schematox'
@@ -125,10 +139,7 @@ parsed.data
     // ^? User
 ```
 
-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.
-
-## Transform static schema into struct
+### Construct
 
 ```typescript
 import { makeStruct } from 'schematox'
@@ -138,14 +149,9 @@ const schema = { type: 'string' } as const satisfies Schema
 const string = makeStruct(schema)
 ```
 
-## Example for all supported schema types
+## Primitive Schema
 
-We distinguish two main categories of schema units:
-
-- 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.
+Any schema share optional/nullable/description/brand parameters.
 
 ### Boolean
 
@@ -249,6 +255,10 @@ type FromStruct = Infer<typeof struct>
 //
 ```
 
+## Compound Schema
+
+Any compound schema could have any other schema type as its member including itself.
+
 ### Array
 
 ```typescript
@@ -372,15 +382,15 @@ type FromSchema = Infer<typeof schema>
 type FromStruct = Infer<typeof struct>
 ```
 
-## Schema parameters
+## Schema Parameters
 
-- `optional?: boolean` –  unionize with `undefined`: `{ type: 'string', optinoal: true }` result in `string | undefined`
+- `optional?: boolean` – unionize with `undefined`: `{ type: 'string', optinoal: true }` result in `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
-- `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
+- `brand?: [string, unknown]` – 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
+## Error Shape
 
 Nested schema example. Subject `0` is invalid, should be a `string`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematox",
-  "version": "1.0.0",
+  "version": "1.1.0-alpha",
   "scripts": {
     "prepublishOnly": "bash release-check.sh",
     "test": "jest",

package/src/constants.ts

@@ -16,3 +16,8 @@ export const PARAMS_BY_SCHEMA_TYPE = {
   tuple:    new Set(['optional', 'nullable', 'description'] as const),
   union:    new Set(['optional', 'nullable', 'description'] as const),
 } as const
+
+export const STANDARD_SCHEMA = {
+  version: 1,
+  vendor: 'schematox',
+} as const

package/src/struct.ts

@@ -1,15 +1,31 @@
-import { PARAMS_BY_SCHEMA_TYPE } from './constants'
+import { PARAMS_BY_SCHEMA_TYPE, STANDARD_SCHEMA } from './constants'
 import { parse } from './parse'
 
-import type { Schema, StringSchema } from './types/schema'
+import type { StandardSchemaV1 } from './types/standard-schema'
+import type { Schema, BrandSchema, StringSchema } from './types/schema'
 import type { Struct, StructParams, StructShape } from './types/struct'
 
 export function makeStruct<T extends Schema>(schema: T): Struct<T>
 export function makeStruct(schema: Schema) {
   const params = PARAMS_BY_SCHEMA_TYPE[schema.type] as Set<StructParams>
-  const result: Record<string, unknown> = {
+  const result: Record<string, unknown> & StandardSchemaV1 = {
     __schema: { ...schema },
     parse: (subj: unknown) => parse(schema as never, subj),
+    ['~standard']: {
+      ...STANDARD_SCHEMA,
+      validate: (input) => {
+        const parsed = parse(schema as never, input)
+
+        return parsed.success
+          ? { value: parsed.data }
+          : {
+              issues: parsed.error.map((x) => ({
+                path: x.path,
+                message: x.code,
+              })),
+            }
+      },
+    },
   }
 
   if (params.has('optional')) {
@@ -26,8 +42,12 @@ export function makeStruct(schema: Schema) {
   }
 
   if (params.has('brand')) {
-    result.brand = (key: string, value: string) =>
-      makeStruct({ ...schema, brand: [key, value] })
+    result.brand = (...args: BrandSchema | [BrandSchema]) => {
+      return makeStruct({
+        ...schema,
+        brand: (Array.isArray(args[0]) ? args[0] : args) as BrandSchema,
+      })
+    }
   }
 
   if (params.has('min')) {

package/src/types/schema.ts

@@ -8,9 +8,7 @@ export type Schema =
    | { type: 'tuple'; of: Array<Schema> } & SchemaShared
    | { type: 'union'; of: Array<Schema> } & SchemaShared
 
-export type BrandSchema<T = string, U = unknown> = Readonly<
-  [category: T, subCategory: U]
->
+export type BrandSchema<T = string, U = unknown> = Readonly<[T, U]>
 
 export type SchemaShared = {
   /**

package/src/types/standard-schema.ts

@@ -0,0 +1,50 @@
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** Source: https://github.com/standard-schema/standard-schema/blob/main/packages/spec/src/index.ts */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>
+}
+
+export declare namespace StandardSchemaV1 {
+  export interface Props<Input = unknown, Output = Input> {
+    readonly version: 1
+    readonly vendor: string
+    readonly validate: (
+      value: unknown
+    ) => Result<Output> | Promise<Result<Output>>
+    readonly types?: Types<Input, Output> | undefined
+  }
+
+  export type Result<Output> = SuccessResult<Output> | FailureResult
+
+  export interface SuccessResult<Output> {
+    readonly value: Output
+    readonly issues?: undefined
+  }
+
+  export interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>
+  }
+
+  export interface Issue {
+    readonly message: string
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined
+  }
+
+  export interface PathSegment {
+    readonly key: PropertyKey
+  }
+
+  export interface Types<Input = unknown, Output = Input> {
+    readonly input: Input
+    readonly output: Output
+  }
+
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['input']
+
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['output']
+
+  export {}
+}

package/src/types/struct.ts

@@ -1,5 +1,6 @@
 import { ParseResult } from './utils'
 
+import type { StandardSchemaV1 } from './standard-schema'
 import type {
   Schema,
   //
@@ -9,6 +10,8 @@ import type {
   TupleSchema,
   UnionSchema,
   //
+  BrandSchema,
+  //
   BooleanSchema,
   LiteralSchema,
   NumberSchema,
@@ -23,10 +26,19 @@ export type Struct<T extends Schema> = Omit<
       optional: () => Struct<T & { optional: true }>
       nullable: () => Struct<T & { nullable: true }>
 
-      brand: <V extends string, W extends string>(
-        key: V,
-        value: W
-      ) => Struct<T & { brand: Readonly<[V, W]> }>
+      brand: <
+        U extends [string, BrandSubType] | [Readonly<[string, BrandSubType]>],
+      >(
+        ...args: U
+      ) => Struct<
+        T & {
+          brand: U extends [infer V, infer W]
+            ? BrandSchema<V, W>
+            : U extends [Readonly<[infer V, infer W]>]
+              ? BrandSchema<V, W>
+              : never
+        }
+      >
 
       minLength: <U extends number>(
         minLength: U
@@ -48,7 +60,14 @@ export type Struct<T extends Schema> = Omit<
 > & {
   __schema: Readonly<T>
   parse: (s: unknown) => ParseResult<InferSchema<T>>
-}
+} & StandardSchemaV1<unknown, InferSchema<T>>
+
+type BrandSubType =
+  | boolean
+  | number
+  | string
+  | ReadonlyArray<unknown>
+  | Record<string, unknown>
 
 export type StructShape<T> = { __schema: T }