@loro-extended/change 1.0.1 → 1.1.0

package/README.md

@@ -497,6 +497,46 @@ const schema = Shape.doc({
 - `Shape.plain.union(shapes)` - Union of value types (e.g., `string | null`)
 - `Shape.plain.discriminatedUnion(key, variants)` - Tagged union types with a discriminant key
 
+#### Nullable Values
+
+Use `.nullable()` on value types to create nullable fields with `null` as the default placeholder:
+
+```typescript
+const schema = Shape.doc({
+  profile: Shape.struct({
+    name: Shape.plain.string().placeholder("Anonymous"),
+    email: Shape.plain.string().nullable(),        // string | null, defaults to null
+    age: Shape.plain.number().nullable(),          // number | null, defaults to null
+    verified: Shape.plain.boolean().nullable(),    // boolean | null, defaults to null
+    tags: Shape.plain.array(Shape.plain.string()).nullable(),  // string[] | null
+    metadata: Shape.plain.record(Shape.plain.string()).nullable(), // Record<string, string> | null
+    location: Shape.plain.struct({                 // { lat: number, lng: number } | null
+      lat: Shape.plain.number(),
+      lng: Shape.plain.number(),
+    }).nullable(),
+  }),
+});
+```
+
+You can chain `.placeholder()` after `.nullable()` to customize the default value:
+
+```typescript
+const schema = Shape.doc({
+  settings: Shape.struct({
+    // Nullable string with custom default
+    nickname: Shape.plain.string().nullable().placeholder("Guest"),
+  }),
+});
+```
+
+This is syntactic sugar for the more verbose union pattern:
+
+```typescript
+// These are equivalent:
+email: Shape.plain.string().nullable()
+email: Shape.plain.union([Shape.plain.null(), Shape.plain.string()]).placeholder(null)
+```
+
 ### TypedDoc API
 
 With the proxy-based API, schema properties are accessed directly on the doc object, and meta-operations are accessed via the `$` namespace.

package/dist/index.d.ts

@@ -229,6 +229,13 @@ declare class TextRef extends TypedRef<TextContainerShape> {
 type WithPlaceholder<S extends Shape<any, any, any>> = S & {
     placeholder(value: S["_placeholder"]): S;
 };
+/**
+ * Type for value shapes that support the .nullable() method.
+ * Returns a union of null and the original shape with null as the default placeholder.
+ */
+type WithNullable<S extends ValueShape> = {
+    nullable(): WithPlaceholder<UnionValueShape<[NullValueShape, S]>>;
+};
 interface DocShape<NestedShapes extends Record<string, ContainerShape> = Record<string, ContainerShape>> extends Shape<{
     [K in keyof NestedShapes]: NestedShapes[K]["_plain"];
 }, {
@@ -404,9 +411,9 @@ declare const Shape: {
     text: () => WithPlaceholder<TextContainerShape>;
     tree: <T extends MapContainerShape | StructContainerShape>(shape: T) => TreeContainerShape;
     plain: {
-        string: <T extends string = string>(...options: T[]) => WithPlaceholder<StringValueShape<T>>;
-        number: () => WithPlaceholder<NumberValueShape>;
-        boolean: () => WithPlaceholder<BooleanValueShape>;
+        string: <T extends string = string>(...options: T[]) => WithPlaceholder<StringValueShape<T>> & WithNullable<StringValueShape<T>>;
+        number: () => WithPlaceholder<NumberValueShape> & WithNullable<NumberValueShape>;
+        boolean: () => WithPlaceholder<BooleanValueShape> & WithNullable<BooleanValueShape>;
         null: () => NullValueShape;
         undefined: () => UndefinedValueShape;
         uint8Array: () => Uint8ArrayValueShape;
@@ -422,13 +429,13 @@ declare const Shape: {
          * })
          * ```
          */
-        struct: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T>;
+        struct: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T> & WithNullable<StructValueShape<T>>;
         /**
          * @deprecated Use `Shape.plain.struct` instead. `Shape.plain.struct` will be removed in a future version.
          */
-        object: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T>;
-        record: <T extends ValueShape>(shape: T) => RecordValueShape<T>;
-        array: <T extends ValueShape>(shape: T) => ArrayValueShape<T>;
+        object: <T extends Record<string, ValueShape>>(shape: T) => StructValueShape<T> & WithNullable<StructValueShape<T>>;
+        record: <T extends ValueShape>(shape: T) => RecordValueShape<T> & WithNullable<RecordValueShape<T>>;
+        array: <T extends ValueShape>(shape: T) => ArrayValueShape<T> & WithNullable<ArrayValueShape<T>>;
         union: <T extends ValueShape[]>(shapes: T) => WithPlaceholder<UnionValueShape<T>>;
         /**
          * Creates a discriminated union shape for type-safe tagged unions.
@@ -816,4 +823,4 @@ declare class TypedPresence<S extends ContainerShape | ValueShape> {
  */
 declare function validatePlaceholder<T extends DocShape>(placeholder: unknown, schema: T): Infer<T>;
 
-export { type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type Mutable, type ObjectValue, type ObjectValueShape, type PresenceInterface, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructValueShape, type TextContainerShape, type TreeContainerShape, type TypedDoc, TypedPresence, type UnionValueShape, type ValueShape, type WithPlaceholder, change, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, getLoroDoc, mergeValue, overlayPlaceholder, validatePlaceholder };
+export { type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type Mutable, type ObjectValue, type ObjectValueShape, type PresenceInterface, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructValueShape, type TextContainerShape, type TreeContainerShape, type TypedDoc, TypedPresence, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, getLoroDoc, mergeValue, overlayPlaceholder, validatePlaceholder };

package/dist/index.js

@@ -270,6 +270,29 @@ function createPlaceholderProxy(target) {
 }
 
 // src/shape.ts
+function makeNullable(shape) {
+  const nullShape = {
+    _type: "value",
+    valueType: "null",
+    _plain: null,
+    _mutable: null,
+    _placeholder: null
+  };
+  const base = {
+    _type: "value",
+    valueType: "union",
+    shapes: [nullShape, shape],
+    _plain: null,
+    _mutable: null,
+    _placeholder: null
+    // Default placeholder is null
+  };
+  return Object.assign(base, {
+    placeholder(value) {
+      return { ...base, _placeholder: value };
+    }
+  });
+}
 var Shape = {
   doc: (shape) => ({
     _type: "doc",
@@ -382,6 +405,9 @@ var Shape = {
       return Object.assign(base, {
         placeholder(value) {
           return { ...base, _placeholder: value };
+        },
+        nullable() {
+          return makeNullable(base);
         }
       });
     },
@@ -396,6 +422,9 @@ var Shape = {
       return Object.assign(base, {
         placeholder(value) {
           return { ...base, _placeholder: value };
+        },
+        nullable() {
+          return makeNullable(base);
         }
       });
     },
@@ -410,6 +439,9 @@ var Shape = {
       return Object.assign(base, {
         placeholder(value) {
           return { ...base, _placeholder: value };
+        },
+        nullable() {
+          return makeNullable(base);
         }
       });
     },
@@ -446,41 +478,69 @@ var Shape = {
      * })
      * ```
      */
-    struct: (shape) => ({
-      _type: "value",
-      valueType: "struct",
-      shape,
-      _plain: {},
-      _mutable: {},
-      _placeholder: {}
-    }),
+    struct: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "struct",
+        shape,
+        _plain: {},
+        _mutable: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
     /**
      * @deprecated Use `Shape.plain.struct` instead. `Shape.plain.struct` will be removed in a future version.
      */
-    object: (shape) => ({
-      _type: "value",
-      valueType: "struct",
-      shape,
-      _plain: {},
-      _mutable: {},
-      _placeholder: {}
-    }),
-    record: (shape) => ({
-      _type: "value",
-      valueType: "record",
-      shape,
-      _plain: {},
-      _mutable: {},
-      _placeholder: {}
-    }),
-    array: (shape) => ({
-      _type: "value",
-      valueType: "array",
-      shape,
-      _plain: [],
-      _mutable: [],
-      _placeholder: []
-    }),
+    object: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "struct",
+        shape,
+        _plain: {},
+        _mutable: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
+    record: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "record",
+        shape,
+        _plain: {},
+        _mutable: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
+    array: (shape) => {
+      const base = {
+        _type: "value",
+        valueType: "array",
+        shape,
+        _plain: [],
+        _mutable: [],
+        _placeholder: []
+      };
+      return Object.assign(base, {
+        nullable() {
+          return makeNullable(base);
+        }
+      });
+    },
     // Special value type that helps make things like `string | null` representable
     // TODO(duane): should this be a more general type for containers too?
     union: (shapes) => {