Merge branch 'release/v1.0.18'

Author: holtwick

demos/schema-serialization/README.md

@@ -0,0 +1,55 @@
+# Schema Serialization Demo
+
+This demo demonstrates how to serialize and deserialize schema types to/from JSON format.
+
+## What it demonstrates
+
+- Converting schema definitions to plain JSON objects
+- Sending schemas over the network (as JSON strings)
+- Reconstructing schemas from JSON
+- Round-trip serialization (schema → JSON → schema)
+- Working with complex nested schemas
+
+## Use Cases
+
+Schema serialization is useful for:
+
+1. **API Documentation**: Send schema definitions to clients for validation
+2. **Remote Validation**: Share validation rules between client and server
+3. **Database Storage**: Store schema definitions in databases
+4. **Configuration**: Define schemas in JSON configuration files
+5. **Code Generation**: Generate code from serialized schemas
+
+## Running the demo
+
+```bash
+pnpm install
+pnpm start
+```
+
+Or with tsx:
+
+```bash
+npx tsx index.ts
+```
+
+## Key Functions
+
+- `serializeSchema(schema)` - Converts a Type schema to a plain JSON object
+- `deserializeSchema(json)` - Reconstructs a Type schema from a JSON object
+
+## Limitations
+
+- Function-based default values (e.g., `.default(() => 'value')`) cannot be serialized
+- Custom validation functions are not preserved (standard validators are restored)
+- Only static, JSON-serializable values are maintained
+
+## Example Output
+
+The demo will show:
+
+1. The original schema structure
+2. The serialized JSON representation
+3. The deserialized schema (identical to the original)
+4. Round-trip verification
+5. Complex nested schema serialization

demos/schema-serialization/index.ts

@@ -0,0 +1,87 @@
+/* eslint-disable no-console */
+
+/**
+ * Schema Serialization Demo
+ *
+ * This demo shows how to serialize and deserialize schema types to/from JSON.
+ * This is useful for:
+ * - Sending schema definitions over the network
+ * - Storing schemas in databases
+ * - Sharing schemas between different systems
+ */
+
+import { array, deserializeSchema, int, object, serializeSchema, string, z } from 'zeed'
+
+// Define a user schema
+const userSchema = z.object({
+  id: z.string().default('auto-generated'),
+  name: z.string().describe('Full name of the user'),
+  email: z.string(),
+  age: z.int().optional(),
+  role: z.enum(['admin', 'user', 'guest']).default('user'),
+  tags: z.array(z.string()).optional(),
+  metadata: z.object({
+    createdAt: z.string(),
+    updatedAt: z.string().optional(),
+  }).optional(),
+})
+
+console.log('Original schema:')
+console.log(userSchema)
+
+// Serialize the schema to a plain JSON object
+const serialized = serializeSchema(userSchema)
+console.log('\nSerialized schema:')
+console.log(JSON.stringify(serialized, null, 2))
+
+// Convert to JSON string (as you might send over network)
+const jsonString = JSON.stringify(serialized)
+console.log('\nJSON string length:', jsonString.length)
+
+// Deserialize back to a schema
+const deserialized = deserializeSchema(JSON.parse(jsonString))
+console.log('\nDeserialized schema:')
+console.log(deserialized)
+
+// Use the deserialized schema to validate data
+const userData = {
+  name: 'Alice Smith',
+  email: '[email protected]',
+  age: 30,
+  role: 'admin',
+  tags: ['developer', 'typescript'],
+}
+
+console.log('\nValidating data with deserialized schema:')
+console.log('Input:', userData)
+
+// Note: You would use a parsing function here when available
+// For now, we can just verify the schema structure is correct
+console.log('Schema type:', deserialized.type)
+console.log('Schema has object definition:', !!deserialized._object)
+console.log('Name field type:', deserialized._object.name.type)
+console.log('Role field enum values:', deserialized._object.role._enumValues)
+console.log('Age field is optional:', deserialized._object.age._optional)
+
+// Demonstrate round-trip serialization
+const reserialized = serializeSchema(deserialized)
+const areEqual = JSON.stringify(serialized) === JSON.stringify(reserialized)
+console.log('\nRound-trip successful:', areEqual)
+
+// Example of a complex nested schema
+const apiResponseSchema = object({
+  success: z.boolean(),
+  data: z.object({
+    users: array(userSchema),
+    total: int(),
+  }),
+  error: string().optional(),
+})
+
+console.log('\n--- Complex Schema Example ---')
+const complexSerialized = serializeSchema(apiResponseSchema)
+console.log('Complex schema serialized:')
+console.log(JSON.stringify(complexSerialized, null, 2))
+
+const complexDeserialized = deserializeSchema(complexSerialized)
+console.log('\nComplex schema deserialized successfully:', complexDeserialized.type === 'object')

demos/schema-serialization/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "demo-schema-serialization",
+  "type": "module",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "tsx index.ts"
+  },
+  "dependencies": {
+    "zeed": "file:../.."
+  },
+  "devDependencies": {
+    "tsx": "^4.20.6"
+  }
+}

package.json

@@ -1,8 +1,8 @@
 {
   "name": "zeed",
   "type": "module",
-  "version": "1.0.17",
-  "packageManager": "pnpm@10.17.0",
+  "version": "1.0.18",
+  "packageManager": "pnpm@10.18.0",
   "description": "🌱 Simple foundation library",
   "author": {
     "name": "Dirk Holtwick",
@@ -81,18 +81,18 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^5.4.1",
-    "@antfu/ni": "^25.0.0",
-    "@types/node": "^24.5.2",
+    "@antfu/ni": "^26.1.0",
+    "@types/node": "^24.6.2",
     "@vitejs/plugin-vue": "^6.0.1",
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
     "esbuild": "^0.25.10",
-    "eslint": "^9.36.0",
+    "eslint": "^9.37.0",
     "playwright": "^1.55.1",
     "pnpm": "^10.17.1",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
-    "vite": "^7.1.7",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.9",
     "vitest": "^3.2.4"
   }
 }

src/common/schema/README.md

@@ -84,6 +84,37 @@ const rpcCall = z.rpc(z.object({ id: z.string() }), z.number())
 // Type: (info: { id: string }) => number | Promise<number>
 ```
 
+### Serialization and Deserialization
+
+You can serialize schema definitions to plain JSON objects and deserialize them back. This is useful for sending schema definitions over the network or storing them in databases.
+
+```ts
+import { deserializeSchema, serializeSchema } from './schema'
+
+// Define a schema
+const userSchema = z.object({
+  name: z.string(),
+  age: z.number().optional(),
+  role: z.stringLiterals(['admin', 'user']).default('user'),
+})
+
+// Serialize to plain JSON
+const serialized = serializeSchema(userSchema)
+// Result: { type: 'object', object: { name: { type: 'string' }, ... } }
+
+// Send over network, store in DB, etc.
+const jsonString = JSON.stringify(serialized)
+
+// Deserialize back to a schema
+const deserialized = deserializeSchema(JSON.parse(jsonString))
+// deserialized is now a Type instance identical to userSchema
+
+// Use the deserialized schema for validation
+const user = deserialized.parse({ name: 'Alice', role: 'admin' })
+```
+
+**Note**: Function defaults (e.g., `.default(() => 'value')`) cannot be serialized and will be omitted. Only static default values are preserved during serialization.
+
 ## API Reference
 
 - `string()`, `number()`, `int()`, `boolean()`, `none()`, `any()`
@@ -93,6 +124,8 @@ const rpcCall = z.rpc(z.object({ id: z.string() }), z.number())
 - `func(args, ret)`, `rpc(info, ret)`
 - `.optional()`, `.default(value)`, `.meta({ desc })`, `.extend({...})`
 - `parse(obj)`, `map(obj, fn)`
+- `serializeSchema(schema)` - Converts a schema to a plain JSON object
+- `deserializeSchema(json)` - Reconstructs a schema from a JSON object
 
 ## Notes
 

src/common/schema/index.ts

@@ -5,6 +5,7 @@ export * from './parse-args'
 export * from './parse-env'
 export * from './parse-object'
 export * from './schema'
+export * from './serialize'
 export * from './type-test'
 export * from './utils'
 export * from './z'

src/common/schema/parse-object.spec.ts

@@ -218,5 +218,24 @@ describe('schema parse obj', () => {
       },
       // optionalObj is missing (not undefined) since it's optional and not provided
     })
+
+    const configSchema = z.object({
+      cspAllowedDomains: z.string().default('*.holtwick.de *.brie.fi *.apperdeck.com *.replies.io *.sentry.io').describe('Allowed domains for Content-Security-Policy, space separated. Use * as wildcard.'),
+      hstsMaxAge: z.number().default(31536000).describe('Max age for HTTP Strict Transport Security (HSTS) in seconds. Set to 0 to disable.'),
+      securityHeaders: z.boolean().default(true).describe('Enable security headers like Content-Security-Policy, X-Frame-Options, etc.'),
+      trustProxy: z.boolean().default(true).describe('Trust the X-Forwarded-* headers, useful if you run behind a reverse proxy.'),
+    })
+
+    const result5 = schemaParseObject(configSchema, {
+      securityHeaders: 'false',
+      hstsMaxAge: '0',
+      notAllowed: 'should be kept',
+    }, {
+      skipDefault: true,
+    })
+    expect(result5).toEqual({
+      securityHeaders: false,
+      hstsMaxAge: 0,
+    })
   })
 })