tinybase 7.0.1 → 7.1.0-beta.1

package/@types/schematizers/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The schematizers module provides utilities for converting schemas from
+ * popular validation libraries into TinyBase's schema format.
+ *
+ * Schematizers perform "best-effort" conversion, extracting basic type
+ * information (string, number, boolean) and default values while discarding
+ * complex validation rules that TinyBase doesn't support.
+ * @packageDocumentation
+ * @module schematizers
+ * @since v7.1.0
+ */
+import type {TablesSchema, ValuesSchema} from '../store/index.d.ts';
+
+/**
+ * The Schematizer interface represents a schema converter that can transform
+ * external validation library schemas into TinyBase TablesSchema and
+ * ValuesSchema formats.
+ * @category Schematizer
+ * @since v7.1.0
+ */
+export interface Schematizer {
+  /**
+ * The toTablesSchema method converts a mapping of external schemas into a
+ * TinyBase TablesSchema.
+ * @param schemas - A mapping of table IDs to external schema objects.
+ * @returns A TinyBase TablesSchema.
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toTablesSchema(schemas: any): TablesSchema;
+
+  /**
+ * The toValuesSchema method converts a mapping of external schemas into a
+ * TinyBase ValuesSchema.
+ * @param schemas - A mapping of value IDs to external schema objects.
+ * @returns A TinyBase ValuesSchema.
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toValuesSchema(schemas: any): ValuesSchema;
+}

package/@types/schematizers/schematizer-zod/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The schematizer-zod module provides conversion utilities for Zod schemas.
+ * @packageDocumentation
+ * @module schematizer-zod
+ * @since v7.1.0
+ */
+import type {TablesSchema, ValuesSchema} from '../../store/index.d.ts';
+import type {Schematizer} from '../index.d.ts';
+
+/**
+ * The ZodSchematizer interface represents a schematizer specifically for
+ * converting Zod schemas into TinyBase schemas.
+ * @category Schematizer
+ * @since v7.1.0
+ */
+export interface ZodSchematizer extends Schematizer {
+  /**
+ * The toTablesSchema method converts a mapping of Zod object schemas into a
+ * TinyBase TablesSchema.
+ *
+ * This method extracts basic type information (string, number, boolean),
+ * default values, and nullable flags from Zod schemas. Complex validation
+ * rules like min/max, regex patterns, refinements, and transforms are ignored.
+ * @param schemas - A mapping of table IDs to Zod object schemas.
+ * @returns A TinyBase TablesSchema.
+ * @example
+ * This example converts Zod schemas to TinyBase format.
+ *
+ * ```js
+ * import {createStore} from 'tinybase';
+ * import {createZodSchematizer} from 'tinybase/schematizers/schematizer-zod';
+ * import {z} from 'zod';
+ *
+ * const schematizer = createZodSchematizer();
+ *
+ * const tablesSchema = schematizer.toTablesSchema({
+ *   pets: z.object({
+ *     species: z.string(),
+ *     age: z.number(),
+ *     sold: z.boolean().default(false),
+ *   }),
+ * });
+ *
+ * const store = createStore().setTablesSchema(tablesSchema);
+ * store.setRow('pets', 'fido', {species: 'dog', age: 3});
+ * console.log(store.getRow('pets', 'fido'));
+ * // -> {species: 'dog', age: 3, sold: false}
+ * ```
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toTablesSchema(schemas: {[tableId: string]: any}): TablesSchema;
+
+  /**
+ * The toValuesSchema method converts a mapping of Zod schemas into a TinyBase
+ * ValuesSchema.
+ *
+ * This method extracts basic type information and default values from Zod
+ * schemas.
+ * @param schemas - A mapping of value IDs to Zod schemas.
+ * @returns A TinyBase ValuesSchema.
+ * @example
+ * This example converts Zod value schemas.
+ *
+ * ```js
+ * import {createStore} from 'tinybase';
+ * import {createZodSchematizer} from 'tinybase/schematizers/schematizer-zod';
+ * import {z} from 'zod';
+ *
+ * const schematizer = createZodSchematizer();
+ *
+ * const valuesSchema = schematizer.toValuesSchema({
+ *   theme: z.string().default('light'),
+ *   count: z.number(),
+ * });
+ *
+ * const store = createStore().setValuesSchema(valuesSchema);
+ * console.log(store.getValues());
+ * // -> {theme: 'light'}
+ * ```
+ * @category Conversion
+ * @since v7.1.0
+ */
+  toValuesSchema(schemas: {[valueId: string]: any}): ValuesSchema;
+}
+
+/**
+ * The createZodSchematizer function creates a ZodSchematizer object that can
+ * convert Zod schemas into TinyBase schemas.
+ *
+ * The schematizer is stateless and can be reused for multiple conversions.
+ * @returns A new ZodSchematizer instance.
+ * @example
+ * This example creates a Zod schematizer and uses it to convert schemas.
+ *
+ * ```js
+ * import {createZodSchematizer} from 'tinybase/schematizers/schematizer-zod';
+ * import {z} from 'zod';
+ *
+ * const schematizer = createZodSchematizer();
+ *
+ * const tablesSchema = schematizer.toTablesSchema({
+ *   pets: z.object({
+ *     species: z.string(),
+ *   }),
+ * });
+ * console.log(tablesSchema);
+ * // -> {pets: {species: {type: 'string'}}}
+ * ```
+ * @category Creation
+ * @since v7.1.0
+ */
+export function createZodSchematizer(): ZodSchematizer;

package/@types/schematizers/schematizer-zod/with-schemas/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The schematizer-zod module provides conversion utilities for Zod schemas.
+ * @packageDocumentation
+ * @module schematizer-zod
+ * @since v7.1.0
+ */
+export type {
+  ZodSchematizer,
+  createZodSchematizer,
+} from '../../schematizer-zod/index.d.ts';

package/@types/schematizers/with-schemas/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The schematizers module provides utilities for converting schemas from
+ * popular validation libraries into TinyBase's schema format.
+ *
+ * Schematizers perform "best-effort" conversion, extracting basic type
+ * information (string, number, boolean) and default values while discarding
+ * complex validation rules that TinyBase doesn't support.
+ * @packageDocumentation
+ * @module schematizers
+ * @since v7.1.0
+ */
+export type {Schematizer} from '../index.d.ts';

package/agents.md

@@ -341,3 +341,147 @@ npx vitest run ./test/unit/documentation.test.ts --retry=0
 2. **Guide Content**: Edit markdown files in `/site/guides/`
 3. **Release Notes**: Edit `/site/guides/16_releases.md` (not `/releases.md`)
 4. **Always run documentation tests** after changes to verify examples work
+
+## Creating New Schematizers
+
+Schematizers convert external schema validation libraries (like Zod) to TinyBase
+schemas. Follow this pattern:
+
+### Module Structure
+
+```
+src/@types/schematizers/schematizer-{library}/
+  index.d.ts           # Type definitions
+  docs.js              # Documentation
+  with-schemas/
+    index.d.ts         # Re-exports for schema-aware variants
+src/schematizers/schematizer-{library}/
+  index.ts             # Implementation
+```
+
+### Factory Pattern
+
+```typescript
+export const createZodSchematizer: typeof createZodSchematizerDecl = () => {
+  const toTablesSchema = (schemas: {[tableId: string]: any}): TablesSchema => {
+    // Best-effort conversion logic
+  };
+
+  const toValuesSchema = (schemas: {[valueId: string]: any}): ValuesSchema => {
+    // Best-effort conversion logic
+  };
+
+  return objFreeze({
+    toTablesSchema,
+    toValuesSchema,
+  });
+};
+```
+
+### Conversion Strategy
+
+- Extract basic types only: `string`, `number`, `boolean`
+- Handle defaults via schema introspection
+- Support nullable and optional modifiers
+- **Ignore** complex types (arrays, objects, etc.) - they won't appear in output
+- Use recursive unwrapping for wrapper types (e.g., `ZodOptional`, `ZodNullable`,
+  `ZodDefault`)
+
+### Implementation Idioms
+
+- Use `objForEach` for iteration, not `for...in` loops
+- Use `ifNotUndefined` for conditional logic
+- Use `objIsEmpty` to filter out empty table schemas
+- Extract string constants to module-level (e.g., `TYPE`, `DEFAULT`,
+  `ALLOW_NULL`)
+- Freeze the returned schematizer object with `objFreeze`
+
+### Example Conversion Logic
+
+```typescript
+const unwrap = (
+  schema: any,
+  defaultValue?: any,
+  allowNull?: boolean,
+): [any, any, boolean] => {
+  const typeName = schema._def?.typeName;
+  return typeName === ZOD_OPTIONAL
+    ? unwrap(schema._def.innerType, defaultValue, allowNull)
+    : typeName === ZOD_NULLABLE
+      ? unwrap(schema._def.innerType, defaultValue, true)
+      : typeName === ZOD_DEFAULT
+        ? unwrap(schema._def.innerType, schema._def.defaultValue(), allowNull)
+        : [schema, defaultValue, allowNull ?? false];
+};
+```
+
+### Build Configuration
+
+- Add module to `ALL_MODULES` array in `gulpfile.mjs`
+- Add peer dependency to `package.json` (marked as optional)
+- Add as dev dependency for testing
+
+### Testing
+
+- Create comprehensive test suite in
+  `test/unit/schematizers/schematizer-{library}.test.ts`
+- Test basic type conversion, defaults, nullable, optional
+- Test unsupported types are filtered out
+- Test integration with actual TinyBase stores
+- Inline schemas directly in test calls (no intermediate variables unless needed
+  multiple times)
+
+### Documentation Testing
+
+Add library import to `test/unit/documentation.test.ts`:
+
+```typescript
+import * as z from 'zod';
+import * as TinyBaseSchematizersZod from 'tinybase/schematizers/schematizer-zod';
+
+(globalThis as any).modules = {
+  ...
+  'tinybase/schematizers/schematizer-zod': TinyBaseSchematizersZod,
+  zod: z,
+};
+```
+
+## Guide Writing Best Practices
+
+### Examples Run Sequentially
+
+All code examples in a guide file are concatenated and executed as a test:
+
+- Use unique variable names (`store`, `store2`, `store3`) to avoid redeclaration
+- First example includes all imports, later examples reuse them
+- Clean up between examples if needed (`store.delTables()`)
+
+### Inline Simple Values
+
+- Prefer inline schemas/data in method calls over intermediate variables
+- Only extract to variables when used multiple times
+- Keeps examples concise and focused
+
+### Guide Chains
+
+- Each guide's summary should link to the next guide in sequence
+- Pattern: "For that we proceed to the [Next Topic] guide."
+- Creates a natural learning path
+
+## Release Notes Updates
+
+When adding a new feature:
+
+1. **Update `/site/guides/16_releases.md`** (NOT `/releases.md`):
+   - Add new version section at the top
+   - Include working code example that will be tested
+   - Link to relevant guide if applicable
+   - Use past releases as template for structure
+
+2. **Update `/site/home/index.md`**:
+   - Update the "NEW!" link to point to new version:
+     `<a href='/guides/releases/#v7-1'>`
+   - Update the tagline:
+     `<span id="one-with">"The one with Schematizers!"</span>`
+
+3. **Generated files update automatically** during build process

package/min/schematizers/index.js

@@ -0,0 +1 @@
+

package/min/schematizers/schematizer-zod/index.js

@@ -0,0 +1 @@
+const e=e=>typeof e,t=e(""),n=e(!0),r=e(0),o="type",l="default",f=e=>(t,n,r)=>e(t)?r?.():n(t),s=e=>null==e,a=f(s),p=f(e=>void 0===e),u=Object,c=e=>u.getPrototypeOf(e),y=u.entries,d=u.keys,i=u.freeze,h=(e=[])=>u.fromEntries(e),T=(e,t)=>((e,t)=>e.forEach(t))(y(e),([e,n])=>t(n,e)),b=(e,t,n)=>{const r=e?.def?.type;return"optional"===r?b(e.def.innerType,t,n):"nullable"===r?b(e.def.innerType,t,!0):r===l?b(e.def.innerType,e.def.defaultValue,n):[e,t,n??!1]},m=()=>{const e=e=>{const[f,s,a]=b(e),u=f?.type;if(u!==t&&u!==r&&u!==n)return;const c={[o]:u};return p(s,e=>{c[l]=e}),a&&(c.allowNull=!0),c};return i({toTablesSchema:t=>{const n=h();return T(t,(t,r)=>{const o=h();var l;p(t?.def?.shape,t=>T(t,(t,n)=>p(e(t),e=>{o[n]=e}))),(e=>!s(e)&&a(c(e),e=>e==u.prototype||s(c(e)),()=>!0))(l=o)&&0==(e=>d(e).length)(l)||(n[r]=o)}),n},toValuesSchema:t=>{const n=h();return T(t,(t,r)=>p(e(t),e=>{n[r]=e})),n}})};export{m as createZodSchematizer};

package/min/schematizers/schematizer-zod/with-schemas/index.js

@@ -0,0 +1 @@
+const e=e=>typeof e,t=e(""),n=e(!0),r=e(0),o="type",l="default",f=e=>(t,n,r)=>e(t)?r?.():n(t),s=e=>null==e,a=f(s),p=f(e=>void 0===e),u=Object,c=e=>u.getPrototypeOf(e),y=u.entries,d=u.keys,i=u.freeze,h=(e=[])=>u.fromEntries(e),T=(e,t)=>((e,t)=>e.forEach(t))(y(e),([e,n])=>t(n,e)),b=(e,t,n)=>{const r=e?.def?.type;return"optional"===r?b(e.def.innerType,t,n):"nullable"===r?b(e.def.innerType,t,!0):r===l?b(e.def.innerType,e.def.defaultValue,n):[e,t,n??!1]},m=()=>{const e=e=>{const[f,s,a]=b(e),u=f?.type;if(u!==t&&u!==r&&u!==n)return;const c={[o]:u};return p(s,e=>{c[l]=e}),a&&(c.allowNull=!0),c};return i({toTablesSchema:t=>{const n=h();return T(t,(t,r)=>{const o=h();var l;p(t?.def?.shape,t=>T(t,(t,n)=>p(e(t),e=>{o[n]=e}))),(e=>!s(e)&&a(c(e),e=>e==u.prototype||s(c(e)),()=>!0))(l=o)&&0==(e=>d(e).length)(l)||(n[r]=o)}),n},toValuesSchema:t=>{const n=h();return T(t,(t,r)=>p(e(t),e=>{n[r]=e})),n}})};export{m as createZodSchematizer};

package/min/schematizers/with-schemas/index.js

@@ -0,0 +1 @@
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinybase",
-  "version": "7.0.1",
+  "version": "7.1.0-beta.1",
   "author": "jamesgpearce",
   "repository": "github:tinyplex/tinybase",
   "license": "MIT",
@@ -41,7 +41,8 @@
     "react-native-sqlite-storage": "^6.0.1",
     "sqlite3": "^5.1.7",
     "ws": "^8.18.3",
-    "yjs": "^13.6.27"
+    "yjs": "^13.6.27",
+    "zod": "^4.1.13"
   },
   "peerDependenciesMeta": {
     "@automerge/automerge-repo": {
@@ -106,6 +107,9 @@
     },
     "yjs": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "main": "./index.js",
@@ -304,6 +308,18 @@
       "relationships/with-schemas": [
         "./@types/relationships/with-schemas/index.d.ts"
       ],
+      "schematizers": [
+        "./@types/schematizers/index.d.ts"
+      ],
+      "schematizers/with-schemas": [
+        "./@types/schematizers/with-schemas/index.d.ts"
+      ],
+      "schematizers/schematizer-zod": [
+        "./@types/schematizers/schematizer-zod/index.d.ts"
+      ],
+      "schematizers/schematizer-zod/with-schemas": [
+        "./@types/schematizers/schematizer-zod/with-schemas/index.d.ts"
+      ],
       "store": [
         "./@types/store/index.d.ts"
       ],
@@ -562,6 +578,18 @@
       "min/relationships/with-schemas": [
         "./@types/relationships/with-schemas/index.d.ts"
       ],
+      "min/schematizers": [
+        "./@types/schematizers/index.d.ts"
+      ],
+      "min/schematizers/with-schemas": [
+        "./@types/schematizers/with-schemas/index.d.ts"
+      ],
+      "min/schematizers/schematizer-zod": [
+        "./@types/schematizers/schematizer-zod/index.d.ts"
+      ],
+      "min/schematizers/schematizer-zod/with-schemas": [
+        "./@types/schematizers/schematizer-zod/with-schemas/index.d.ts"
+      ],
       "min/store": [
         "./@types/store/index.d.ts"
       ],
@@ -1015,6 +1043,30 @@
         "default": "./relationships/index.js"
       }
     },
+    "./schematizers": {
+      "default": {
+        "types": "./@types/schematizers/index.d.ts",
+        "default": "./schematizers/index.js"
+      }
+    },
+    "./schematizers/with-schemas": {
+      "default": {
+        "types": "./@types/schematizers/with-schemas/index.d.ts",
+        "default": "./schematizers/index.js"
+      }
+    },
+    "./schematizers/schematizer-zod": {
+      "default": {
+        "types": "./@types/schematizers/schematizer-zod/index.d.ts",
+        "default": "./schematizers/schematizer-zod/index.js"
+      }
+    },
+    "./schematizers/schematizer-zod/with-schemas": {
+      "default": {
+        "types": "./@types/schematizers/schematizer-zod/with-schemas/index.d.ts",
+        "default": "./schematizers/schematizer-zod/index.js"
+      }
+    },
     "./store": {
       "default": {
         "types": "./@types/store/index.d.ts",
@@ -1531,6 +1583,30 @@
         "default": "./min/relationships/index.js"
       }
     },
+    "./min/schematizers": {
+      "default": {
+        "types": "./@types/schematizers/index.d.ts",
+        "default": "./min/schematizers/index.js"
+      }
+    },
+    "./min/schematizers/with-schemas": {
+      "default": {
+        "types": "./@types/schematizers/with-schemas/index.d.ts",
+        "default": "./min/schematizers/index.js"
+      }
+    },
+    "./min/schematizers/schematizer-zod": {
+      "default": {
+        "types": "./@types/schematizers/schematizer-zod/index.d.ts",
+        "default": "./min/schematizers/schematizer-zod/index.js"
+      }
+    },
+    "./min/schematizers/schematizer-zod/with-schemas": {
+      "default": {
+        "types": "./@types/schematizers/schematizer-zod/with-schemas/index.d.ts",
+        "default": "./min/schematizers/schematizer-zod/index.js"
+      }
+    },
     "./min/store": {
       "default": {
         "types": "./@types/store/index.d.ts",