Merge branch 'release/v0.28.18'

Author: holtwick

package.json

@@ -1,7 +1,7 @@
 {
   "name": "zeed",
   "type": "module",
-  "version": "0.28.17",
+  "version": "0.28.18",
   "packageManager": "pnpm@10.11.0",
   "description": "🌱 Simple foundation library",
   "author": {

src/common/schema/README.md

@@ -0,0 +1,100 @@
+# Schema Type System
+
+This module provides a flexible, TypeScript-friendly schema/type system for runtime validation, parsing, and type inference. It is inspired by libraries like [valita](https://github.com/badrap/valita).
+
+## Features
+- Define schemas for primitives, objects, arrays, tuples, unions, literals, and functions
+- Parse and validate data at runtime
+- Type inference for static TypeScript types
+- Extensible and composable
+
+## Installation
+
+This module is part of the `github-zeed` project. To use it, import from the appropriate path:
+
+```ts
+import { array, Infer, literal, number, object, string, union, z } from './schema'
+// z.string and string are functionally alike, but z.string is preferred for consistency.
+```
+
+## Basic Usage
+
+### Primitives
+
+```ts
+const name = z.string()
+const age = z.number()
+// Type: string, number
+```
+
+### Objects
+
+```ts
+const user = z.object({
+  name: z.string(),
+  age: z.number().optional(),
+})
+// Type: { name: string; age?: number }
+```
+
+### Arrays
+
+```ts
+const tags = z.array(z.string())
+// Type: string[]
+```
+
+### Unions
+
+```ts
+const status = z.union([
+  z.literal('active'),
+  z.literal('inactive'),
+])
+// Type: 'active' | 'inactive'
+```
+
+### Type Inference
+
+```ts
+type User = Infer<typeof user>
+// Equivalent to: { name: string; age?: number }
+```
+
+### Parsing
+
+```ts
+const parsed = user.parse({ name: 'Alice', age: 30 })
+// parsed: { name: 'Alice', age: 30 }
+```
+
+### Optional and Default Values
+
+```ts
+const score = z.number().optional().default(0)
+// Type: number | undefined (default: 0)
+```
+
+### Function and RPC Types
+
+```ts
+const add = z.func([z.number(), z.number()], z.number())
+// Type: (a: number, b: number) => number
+const rpcCall = z.rpc(z.object({ id: z.string() }), z.number())
+// Type: (info: { id: string }) => number | Promise<number>
+```
+
+## API Reference
+
+- `string()`, `number()`, `int()`, `boolean()`, `none()`, `any()`
+- `object({...})`, `array(type)`, `tuple([type1, type2, ...])`, `record(type)`
+- `union([type1, type2, ...])`
+- `literal(value)`, `stringLiterals(['a', 'b', ...])`
+- `func(args, ret)`, `rpc(info, ret)`
+- `.optional()`, `.default(value)`, `.props({ desc })`, `.extend({...})`
+- `parse(obj)`, `map(obj, fn)`
+
+## Notes
+
+- `z.string` and `string` are functionally equivalent, but `z.string` is preferred for consistency and clarity.
+- Each schema definition results in a corresponding TypeScript type, which can be extracted using `Infer<typeof schema>`.

src/common/schema/export-json-schema.spec.ts

@@ -0,0 +1,68 @@
+import type { Infer } from './schema'
+import { schemaExportJsonSchema } from './export-json-schema'
+import { z } from './schema'
+
+describe('json-schema.spec', () => {
+  it('parse args', async () => {
+    const schema = z.object({
+      fixed: z.enum(['a', 'b', 'c']).describe('This is a fixed value'),
+      anInt: z.int().optional().default(0),
+      aBool: z.boolean().describe('This is a boolean'),
+      aNumber: z.number().props({
+        desc: 'This is a number',
+      }),
+      aString: z.string(),
+    })
+
+    type t = Infer<typeof schema>
+    expectTypeOf<t>().toMatchObjectType<{
+      fixed: 'a' | 'b' | 'c'
+      anInt?: number | undefined
+      aBool: boolean
+      aNumber: number
+      aString: string
+    }>()
+
+    const r = schemaExportJsonSchema(schema, 'Test')
+
+    expect(r).toMatchInlineSnapshot(`
+      "{
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "Test",
+        "type": "object",
+        "properties": {
+          "fixed": {
+            "type": "string",
+            "enum": [
+              "a",
+              "b",
+              "c"
+            ],
+            "description": "This is a fixed value"
+          },
+          "anInt": {
+            "type": "integer",
+            "default": 0
+          },
+          "aBool": {
+            "type": "boolean",
+            "description": "This is a boolean"
+          },
+          "aNumber": {
+            "type": "number",
+            "description": "This is a number"
+          },
+          "aString": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "fixed",
+          "aBool",
+          "aNumber",
+          "aString"
+        ]
+      }"
+    `)
+  })
+})

src/common/schema/export-json-schema.ts

@@ -0,0 +1,48 @@
+import type { Type } from './schema'
+import { assert } from '../assert'
+import { objectMap } from '../data/object'
+import { isSchemaObjectFlat } from './utils'
+
+const _mapJsonSchemaType: Record<string, string> = {
+  string: 'string',
+  number: 'number',
+  boolean: 'boolean',
+  int: 'integer',
+  // Add more type mappings as needed
+}
+
+export function schemaExportJsonSchema<T>(schema: Type<T>, name: string = 'Example'): string {
+  assert(isSchemaObjectFlat(schema), 'schema should be a flat object')
+
+  const properties: Record<string, any> = {}
+  const required: string[] = []
+
+  objectMap(schema._object!, (key, schema: Type<any>) => {
+    properties[key] = {
+      type: _mapJsonSchemaType[schema.type] ?? schema.type,
+    }
+    const enumValues = (schema as any)._enumValues
+    if (enumValues) {
+      properties[key].enum = enumValues
+    }
+    if (schema._default !== undefined) {
+      properties[key].default = schema._default
+    }
+    if (schema._props?.desc) {
+      properties[key].description = schema._props.desc
+    }
+    if (schema._optional !== true) {
+      required.push(key)
+    }
+  })
+
+  const jsonSchema = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: name,
+    type: 'object',
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  }
+
+  return JSON.stringify(jsonSchema, null, 2)
+}

src/common/schema/schema.spec.ts

@@ -86,6 +86,13 @@ describe('schema', () => {
             "type": "any",
           },
           "lit": Object {
+            "_enumValues": Array [
+              "active",
+              "trialing",
+              "past_due",
+              "paused",
+              "deleted",
+            ],
             "type": "string",
           },
           "log": Object {

src/common/schema/schema.ts

@@ -24,6 +24,7 @@ export interface Type<T = unknown> {
   parse: (obj: any) => T
   map: (obj: any, fn: (this: Type<T>, obj: any, schema: Type<T>) => any) => any
   props: (props: TypeProps) => Type<T>
+  describe: (msg: string) => Type<T>
   extend: <O>(obj: O) => Type<T & InferObject<O>>
 }
 
@@ -81,6 +82,13 @@ export abstract class TypeClass<T = unknown> implements Type<T> {
     return this
   }
 
+  describe(msg: string) {
+    if (!this._props)
+      this._props = {}
+    this._props.desc = msg
+    return this
+  }
+
   extend: <O>(obj: O) => Type<T & InferObject<O>> = (obj: any) => {
     const newObj = { ...this._object, ...obj }
     return object(newObj) as any
@@ -235,6 +243,7 @@ export function record<T extends Type>(tobj: T): Type<Record<string, Infer<T>>>
 
 type TransformToUnion<T extends (Type<any>)[]> = T extends Array<infer U> ? Infer<U> : never
 
+/// Union of types, like `string | number | boolean`
 export function union<T extends (Type<any>)[]>(options: T): Type<TransformToUnion<T>> {
   return generic<any>(first(options)?.type ?? 'any', {
     // _union: options,
@@ -248,6 +257,15 @@ export function union<T extends (Type<any>)[]>(options: T): Type<TransformToUnio
 
 type Literal = string | number | bigint | boolean
 
+export class TypeStringLiterals<T> extends TypeClass<T> {
+  constructor(values: string[]) {
+    super('string', v => values.includes(v))
+    this._enumValues = values
+  }
+
+  _enumValues: string[]
+}
+
 /// todo: string?
 export function literal<T extends Literal>(value: T): Type<T> {
   return generic<T>('literal', {
@@ -257,12 +275,19 @@ export function literal<T extends Literal>(value: T): Type<T> {
 }
 
 /// Sting that can only be one of the values, like: `"a" | "b" | "c"``
-export function stringLiterals<const T extends readonly string[], O = T[number]>(value: T): Type<O> {
-  return generic<O>('string', {
-    _check: v => value.includes(v),
-  })
+export function stringLiterals<const T extends readonly string[], O = T[number]>(values: T): Type<O> {
+  return new TypeStringLiterals<O>(values as any)
 }
 
+/// Sting that can only be one of the values, like: `"a" | "b" | "c"``
+// function zEnum<const T extends readonly (string | number | boolean | bigint)[], O = T[number]>(value: T): Type<O> {
+//   return generic<O>('enum', {
+//     _check: v => value.includes(v),
+//   })
+// }
+
+// export { zEnum as enum } // Export as enum to avoid conflicts with real enum types
+
 // Functions
 
 type TupleOutput<T extends Type[]> = {
@@ -363,6 +388,7 @@ export const z = {
   boolean,
   none,
   any,
+  enum: stringLiterals,
   object,
   array,
   tuple,