Merge pull request #12 from loro-dev/feat-typed-string

feat: default required is true, add custom string type

Author: Leeeon233

README.md

@@ -50,8 +50,8 @@ import { schema, createStore } from "loro-mirror";
 const todoSchema = schema({
     todos: schema.LoroList(
         schema.LoroMap({
-            id: schema.String({ required: true }),
-            text: schema.String({ required: true }),
+            id: schema.String(),
+            text: schema.String(),
             completed: schema.Boolean({ defaultValue: false }),
         }),
     ),
@@ -95,6 +95,126 @@ store.subscribe((state) => {
 });
 ```
 
+### Schema Definition
+
+Loro Mirror provides a declarative schema system that enables:
+
+- **Type Inference**: Automatically infer TypeScript types for your application state from the schema
+- **Runtime Validation**: Validate data structure and types during `setState` operations or synchronization
+- **Default Value Generation**: Generate sensible default values based on the schema definition
+
+#### Core Concepts
+
+- **Root Schema**: The root object defined via `schema({...})`, containing only Loro container types (Map/List/Text/MovableList).
+- **Field Schema**: A combination of primitive types (string, number, boolean), ignore fields, and Loro containers.
+- **Schema Options (`SchemaOptions`)**:
+  - **`required?: boolean`**: Whether the field is required (default: `true`).
+  - **`defaultValue?: unknown`**: Default value for the field.
+  - **`description?: string`**: Description of the field.
+  - **`validate?: (value) => boolean | string`**: Custom validation function. Return `true` for valid values, or a string as error message for invalid ones.
+
+#### Schema Definition API
+
+- **Primitive Types**:
+  - `schema.String<T extends string = string>(options?)` - String type with optional generic constraint
+  - `schema.Number(options?)` - Number type
+  - `schema.Boolean(options?)` - Boolean type
+  - `schema.Ignore(options?)` - Field that won't sync with Loro, useful for local computed fields
+
+- **Container Types**:
+  - `schema.LoroMap(definition, options?)` - Object container that can nest arbitrary field schemas
+    - Supports dynamic key-value definition with `catchall`: `schema.LoroMap({...}).catchall(valueSchema)`
+  - `schema.LoroMapRecord(valueSchema, options?)` - Equivalent to `LoroMap({}).catchall(valueSchema)` for homogeneous maps
+  - `schema.LoroList(itemSchema, idSelector?, options?)` - Ordered list container
+    - Providing an `idSelector` (e.g., `(item) => item.id`) enables minimal add/remove/update/move diffs
+  - `schema.LoroMovableList(itemSchema, idSelector, options?)` - List with native move operations, requires an `idSelector`
+  - `schema.LoroText(options?)` - Collaborative text editing container
+
+#### Type Inference
+
+Automatically derive strongly-typed state from your schema:
+
+```ts
+import { schema } from "loro-mirror";
+
+type UserId = string & { __brand: "userId" }
+const appSchema = schema({
+    user: schema.LoroMap({
+        id: schema.String<UserId>(),
+        name: schema.String(),
+        age: schema.Number({ required: false }),
+    }),
+    tags: schema.LoroList(schema.String()),
+});
+
+// Inferred state type:
+// type AppState = {
+//   user: { id: UserId; name: string; age: number | undefined };
+//   tags: string[];
+// }
+type AppState = InferType<typeof appSchema>;
+```
+
+> **Note**: If you need optional custom string types like `{ id?: UserId }`, you currently need to explicitly define it as `schema.String<UserId>({ required: false })`
+
+For `LoroMap` with dynamic key-value pairs:
+
+```ts
+const mapWithCatchall = schema.LoroMap({ fixed: schema.Number() }).catchall(schema.String());
+// Type: { fixed: number } & { [k: string]: string }
+
+const record = schema.LoroMapRecord(schema.Boolean());
+// Type: { [k: string]: boolean }
+```
+
+When a field has `required: false`, the corresponding type becomes optional (union with `undefined`).
+
+#### Default Values & Creation
+
+- Explicitly specified `defaultValue` takes the highest precedence.
+- Built-in defaults for fields without `defaultValue` and `required: true`:
+  - **String / LoroText** → `""`
+  - **Number** → `0`
+  - **Boolean** → `false`
+  - **LoroList** → `[]`
+  - **LoroMap / Root** → Recursively aggregated defaults from child fields
+
+#### Runtime Validation
+
+`Mirror` validates against the schema when `validateUpdates` is enabled (default: `true`). You can also validate directly:
+
+```ts
+import { validateSchema } from "loro-mirror";
+
+const result = validateSchema(appSchema, {
+    user: { id: "u1", name: "Alice", age: 18 },
+    tags: ["a", "b"],
+});
+// result = { valid: boolean; errors?: string[] }
+```
+
+#### Lists & Movement
+
+- `LoroList(item, idSelector?)`: Providing an `idSelector` enables more stable add/remove/update/move diffs; otherwise uses index-based comparison.
+- `LoroMovableList(item, idSelector)`: Native move operations (preserves element identity), ideal for drag-and-drop scenarios.
+
+```ts
+const todoSchema = schema({
+    todos: schema.LoroMovableList(
+        schema.LoroMap({
+            id: schema.String(),
+            text: schema.String(),
+            completed: schema.Boolean({ defaultValue: false }),
+        }),
+        (t) => t.id,
+    ),
+});
+```
+
+#### Ignored Fields
+
+- Fields defined with `schema.Ignore()` won't sync with Loro, commonly used for derived/cached fields. Runtime validation always passes for these fields.
+
 ### React Usage
 
 ```tsx

packages/core/package.json

@@ -37,4 +37,4 @@
         "loro-crdt": "^1.5.12",
         "typescript": "^5.3.3"
     }
-}
+}

packages/core/src/schema/index.ts

@@ -4,17 +4,21 @@
  * This module provides utilities to define schemas that map between JavaScript types and Loro CRDT types.
  */
 import {
+    BooleanSchemaType,
     ContainerSchemaType,
+    IgnoreSchemaType,
     LoroListSchema,
     LoroMapSchema,
     LoroMapSchemaWithCatchall,
     LoroMovableListSchema,
     LoroTextSchemaType,
+    NumberSchemaType,
     RootSchemaDefinition,
     RootSchemaType,
     SchemaDefinition,
     SchemaOptions,
     SchemaType,
+    StringSchemaType,
 } from "./types";
 
 export * from "./types";
@@ -23,87 +27,87 @@ export * from "./validators";
 /**
  * Create a schema definition
  */
-export function schema<T extends Record<string, ContainerSchemaType>>(
+export function schema<T extends Record<string, ContainerSchemaType>, O extends SchemaOptions = {}>(
     definition: RootSchemaDefinition<T>,
-    options?: SchemaOptions,
-): RootSchemaType<T> {
+    options?: O,
+): RootSchemaType<T> & { options: O } {
     return {
         type: "schema" as const,
         definition,
-        options: options || {},
+        options: options || ({} as O),
         getContainerType() {
             return "Map";
         },
-    };
+    } as RootSchemaType<T> & { options: O };
 }
 
 /**
  * Define a string field
  */
-schema.String = function (options?: SchemaOptions) {
+schema.String = function <T extends string = string, O extends SchemaOptions = {}>(options?: O) {
     return {
         type: "string" as const,
-        options: options || {},
-        getContainerType() {
-            return null; // Primitive type, no container
+        options: (options || {}) as O,
+        getContainerType: () => {
+            return null;
         },
-    };
+    } as StringSchemaType<T> & { options: O };
 };
 
 /**
  * Define a number field
  */
-schema.Number = function (options?: SchemaOptions) {
+schema.Number = function <O extends SchemaOptions = {}>(options?: O) {
     return {
         type: "number" as const,
-        options: options || {},
-        getContainerType() {
+        options: options || ({} as O),
+        getContainerType: () => {
             return null; // Primitive type, no container
         },
-    };
+    } as NumberSchemaType & { options: O };
 };
 
 /**
  * Define a boolean field
  */
-schema.Boolean = function (options?: SchemaOptions) {
+schema.Boolean = function <O extends SchemaOptions = {}>(options?: O) {
     return {
         type: "boolean" as const,
-        options: options || {},
-        getContainerType() {
+        options: options || ({} as O),
+        getContainerType: () => {
             return null; // Primitive type, no container
         },
-    };
+    } as BooleanSchemaType & { options: O };
 };
 
 /**
  * Define a field to be ignored (not synced with Loro)
  */
-schema.Ignore = function (options?: SchemaOptions) {
+schema.Ignore = function <O extends SchemaOptions = {}>(options?: O) {
     return {
         type: "ignore" as const,
-        options: options || {},
-        getContainerType() {
+        options: options || ({} as O),
+        getContainerType: () => {
             return null;
         },
-    };
+    } as IgnoreSchemaType & { options: O };
 };
 
 /**
  * Define a Loro map
  */
-schema.LoroMap = function <T extends Record<string, SchemaType>>(
+schema.LoroMap = function <T extends Record<string, SchemaType> = {}, O extends SchemaOptions = {}>(
     definition: SchemaDefinition<T>,
-    options?: SchemaOptions,
-): LoroMapSchema<T> & { catchall: <C extends SchemaType>(catchallSchema: C) => LoroMapSchemaWithCatchall<T, C> } {
+    options?: O,
+): LoroMapSchema<T> & { options: O } & { catchall: <C extends SchemaType>(catchallSchema: C) => LoroMapSchemaWithCatchall<T, C> } {
     const baseSchema = {
         type: "loro-map" as const,
         definition,
-        options: options || {},
+        options: options || ({} as O),
         getContainerType: () => {
             return "Map";
         },
-    } as LoroMapSchema<T>;
+    } as LoroMapSchema<T> & { options: O };
 
     // Add catchall method like zod
     const schemaWithCatchall = {
@@ -123,79 +127,74 @@ schema.LoroMap = function <T extends Record<string, SchemaType>>(
         }
     };
 
-    return schemaWithCatchall as LoroMapSchema<T> & { catchall: <C extends SchemaType>(catchallSchema: C) => LoroMapSchemaWithCatchall<T, C> };
+    return schemaWithCatchall as LoroMapSchema<T> & { options: O } & { catchall: <C extends SchemaType>(catchallSchema: C) => LoroMapSchemaWithCatchall<T, C> };
 };
 
 /**
  * Create a dynamic record schema (like zod's z.record)
  */
-schema.LoroMapRecord = function <T extends SchemaType>(
+schema.LoroMapRecord = function <T extends SchemaType, O extends SchemaOptions = {}>(
     valueSchema: T,
-    options?: SchemaOptions,
-): LoroMapSchemaWithCatchall<{}, T> {
+    options?: O,
+): LoroMapSchemaWithCatchall<{}, T> & { options: O } {
     return {
         type: "loro-map" as const,
         definition: {},
         catchallType: valueSchema,
-        options: options || {},
+        options: options || ({} as O),
         getContainerType: () => {
             return "Map";
         },
         catchall: <NewC extends SchemaType>(newCatchallSchema: NewC): LoroMapSchemaWithCatchall<{}, NewC> => {
             return schema.LoroMapRecord(newCatchallSchema, options);
         }
-    } as LoroMapSchemaWithCatchall<{}, T>;
+    } as LoroMapSchemaWithCatchall<{}, T> & { options: O };
 };
 
 /**
  * Define a Loro list
- *
- * Optional `idSelector` enables more efficient updates by tracking items by stable IDs
- * rather than by position.
  */
-schema.LoroList = function <T extends SchemaType>(
+schema.LoroList = function <T extends SchemaType, O extends SchemaOptions = {}>(
     itemSchema: T,
-    // oxlint-disable-next-line no-explicit-any
     idSelector?: (item: any) => string,
-    options?: SchemaOptions,
-): LoroListSchema<T> {
+    options?: O,
+): LoroListSchema<T> & { options: O } {
     return {
         type: "loro-list" as const,
         itemSchema,
         idSelector,
-        options: options || {},
-        getContainerType() {
+        options: options || ({} as O),
+        getContainerType: () => {
             return "List";
         },
-    };
+    } as LoroListSchema<T> & { options: O };
 };
 
-schema.LoroMovableList = function <T extends SchemaType>(
+schema.LoroMovableList = function <T extends SchemaType, O extends SchemaOptions = {}>(
     itemSchema: T,
-    // oxlint-disable-next-line no-explicit-any
     idSelector: (item: any) => string,
-    options?: SchemaOptions,
-): LoroMovableListSchema<T> {
+    options?: O,
+): LoroMovableListSchema<T> & { options: O } {
     return {
         type: "loro-movable-list" as const,
         itemSchema,
         idSelector,
-        options: options || {},
-        getContainerType() {
+        options: options || ({} as O),
+        getContainerType: () => {
             return "MovableList";
         },
-    };
+    } as LoroMovableListSchema<T> & { options: O };
 };
 
 /**
  * Define a Loro text field
  */
-schema.LoroText = function (options?: SchemaOptions): LoroTextSchemaType {
+schema.LoroText = function <O extends SchemaOptions = {}>(options?: O): LoroTextSchemaType & { options: O } {
     return {
         type: "loro-text" as const,
-        options: options || {},
-        getContainerType() {
+        options: options || ({} as O),
+        getContainerType: () => {
             return "Text";
         },
-    };
+    } as LoroTextSchemaType & { options: O };
 };