@loro-extended/change 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loro-extended/change",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A schema-driven, type-safe wrapper for Loro CRDT that provides natural JavaScript syntax for collaborative data mutations",
   "author": "Duane Johnson",
   "license": "MIT",

package/src/change.test.ts

@@ -737,6 +737,257 @@ describe("TypedLoroDoc", () => {
       expect(result.profile.email).toBe("john@example.com")
       expect(result.profile.age).toBeNull()
     })
+
+    describe("Nullable Builder", () => {
+      describe("Basic nullable types", () => {
+        it("should handle nullable string with null placeholder", () => {
+          const schema = Shape.doc({
+            profile: Shape.struct({
+              email: Shape.plain.string().nullable(),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          // Should start with null placeholder
+          expect(typedDoc.toJSON().profile.email).toBeNull()
+
+          // Should accept string value
+          const result = change(typedDoc, draft => {
+            draft.profile.set("email", "test@example.com")
+          }).toJSON()
+
+          expect(result.profile.email).toBe("test@example.com")
+
+          // Should accept null value
+          const result2 = change(typedDoc, draft => {
+            draft.profile.set("email", null)
+          }).toJSON()
+
+          expect(result2.profile.email).toBeNull()
+        })
+
+        it("should handle nullable number with null placeholder", () => {
+          const schema = Shape.doc({
+            stats: Shape.struct({
+              age: Shape.plain.number().nullable(),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          expect(typedDoc.toJSON().stats.age).toBeNull()
+
+          const result = change(typedDoc, draft => {
+            draft.stats.set("age", 25)
+          }).toJSON()
+
+          expect(result.stats.age).toBe(25)
+        })
+
+        it("should handle nullable boolean with null placeholder", () => {
+          const schema = Shape.doc({
+            settings: Shape.struct({
+              enabled: Shape.plain.boolean().nullable(),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          expect(typedDoc.toJSON().settings.enabled).toBeNull()
+
+          const result = change(typedDoc, draft => {
+            draft.settings.set("enabled", true)
+          }).toJSON()
+
+          expect(result.settings.enabled).toBe(true)
+        })
+
+        it("should handle nullable record with null placeholder", () => {
+          const schema = Shape.doc({
+            data: Shape.struct({
+              candidates: Shape.plain.record(Shape.plain.string()).nullable(),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          expect(typedDoc.toJSON().data.candidates).toBeNull()
+
+          const result = change(typedDoc, draft => {
+            draft.data.set("candidates", { a: "Alice", b: "Bob" })
+          }).toJSON()
+
+          expect(result.data.candidates).toEqual({ a: "Alice", b: "Bob" })
+
+          // Should accept null value
+          const result2 = change(typedDoc, draft => {
+            draft.data.set("candidates", null)
+          }).toJSON()
+
+          expect(result2.data.candidates).toBeNull()
+        })
+
+        it("should handle nullable array with null placeholder", () => {
+          const schema = Shape.doc({
+            data: Shape.struct({
+              tags: Shape.plain.array(Shape.plain.string()).nullable(),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          expect(typedDoc.toJSON().data.tags).toBeNull()
+
+          const result = change(typedDoc, draft => {
+            draft.data.set("tags", ["a", "b", "c"])
+          }).toJSON()
+
+          expect(result.data.tags).toEqual(["a", "b", "c"])
+
+          // Should accept null value
+          const result2 = change(typedDoc, draft => {
+            draft.data.set("tags", null)
+          }).toJSON()
+
+          expect(result2.data.tags).toBeNull()
+        })
+
+        it("should handle nullable struct with null placeholder", () => {
+          const schema = Shape.doc({
+            data: Shape.struct({
+              point: Shape.plain
+                .struct({
+                  x: Shape.plain.number(),
+                  y: Shape.plain.number(),
+                })
+                .nullable(),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          expect(typedDoc.toJSON().data.point).toBeNull()
+
+          const result = change(typedDoc, draft => {
+            draft.data.set("point", { x: 10, y: 20 })
+          }).toJSON()
+
+          expect(result.data.point).toEqual({ x: 10, y: 20 })
+
+          // Should accept null value
+          const result2 = change(typedDoc, draft => {
+            draft.data.set("point", null)
+          }).toJSON()
+
+          expect(result2.data.point).toBeNull()
+        })
+      })
+
+      describe("Nullable with custom placeholder", () => {
+        it("should allow custom placeholder after nullable()", () => {
+          const schema = Shape.doc({
+            profile: Shape.struct({
+              name: Shape.plain.string().nullable().placeholder("Anonymous"),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          // Should use custom placeholder, not null
+          expect(typedDoc.toJSON().profile.name).toBe("Anonymous")
+
+          // Should still accept null
+          const result = change(typedDoc, draft => {
+            draft.profile.set("name", null)
+          }).toJSON()
+
+          expect(result.profile.name).toBeNull()
+        })
+
+        it("should allow number placeholder after nullable()", () => {
+          const schema = Shape.doc({
+            stats: Shape.struct({
+              score: Shape.plain.number().nullable().placeholder(0),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          expect(typedDoc.toJSON().stats.score).toBe(0)
+        })
+      })
+
+      describe("Type inference", () => {
+        it("should infer correct types for nullable fields", () => {
+          const schema = Shape.doc({
+            data: Shape.struct({
+              nullableString: Shape.plain.string().nullable(),
+              nullableNumber: Shape.plain.number().nullable(),
+              nullableBoolean: Shape.plain.boolean().nullable(),
+            }),
+          })
+
+          const typedDoc = createTypedDoc(schema)
+
+          // TypeScript should allow these assignments
+          change(typedDoc, draft => {
+            draft.data.set("nullableString", "hello")
+            draft.data.set("nullableString", null)
+            draft.data.set("nullableNumber", 42)
+            draft.data.set("nullableNumber", null)
+            draft.data.set("nullableBoolean", true)
+            draft.data.set("nullableBoolean", null)
+          })
+
+          // Verify the types work correctly
+          const json = typedDoc.toJSON()
+          const str: string | null = json.data.nullableString
+          const num: number | null = json.data.nullableNumber
+          const bool: boolean | null = json.data.nullableBoolean
+
+          expect(str).toBeNull()
+          expect(num).toBeNull()
+          expect(bool).toBeNull()
+        })
+      })
+
+      describe("Equivalence to union pattern", () => {
+        it("should behave identically to manual union pattern", () => {
+          // Using nullable()
+          const schema1 = Shape.doc({
+            profile: Shape.struct({
+              email: Shape.plain.string().nullable(),
+            }),
+          })
+
+          // Using manual union
+          const schema2 = Shape.doc({
+            profile: Shape.struct({
+              email: Shape.plain
+                .union([Shape.plain.null(), Shape.plain.string()])
+                .placeholder(null),
+            }),
+          })
+
+          const doc1 = createTypedDoc(schema1)
+          const doc2 = createTypedDoc(schema2)
+
+          // Both should have same initial state
+          expect(doc1.toJSON()).toEqual(doc2.toJSON())
+
+          // Both should accept same operations
+          change(doc1, draft => {
+            draft.profile.set("email", "test@example.com")
+          })
+          change(doc2, draft => {
+            draft.profile.set("email", "test@example.com")
+          })
+
+          expect(doc1.toJSON()).toEqual(doc2.toJSON())
+        })
+      })
+    })
   })
 
   describe("Raw vs Overlaid Values", () => {

package/src/index.ts

@@ -35,6 +35,8 @@ export type {
   UnionValueShape,
   // Value shapes
   ValueShape,
+  // WithNullable type for shapes that support .nullable()
+  WithNullable,
   // WithPlaceholder type for shapes that support .placeholder()
   WithPlaceholder,
 } from "./shape.js"

package/src/shape.ts

@@ -28,6 +28,14 @@ export 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.
+ */
+export type WithNullable<S extends ValueShape> = {
+  nullable(): WithPlaceholder<UnionValueShape<[NullValueShape, S]>>
+}
+
 export interface DocShape<
   NestedShapes extends Record<string, ContainerShape> = Record<
     string,
@@ -258,6 +266,41 @@ export type ValueShape =
 
 export type ContainerOrValueShape = ContainerShape | ValueShape
 
+/**
+ * Creates a nullable version of a value shape.
+ * @internal
+ */
+function makeNullable<S extends ValueShape>(
+  shape: S,
+): WithPlaceholder<UnionValueShape<[NullValueShape, S]>> {
+  const nullShape: NullValueShape = {
+    _type: "value" as const,
+    valueType: "null" as const,
+    _plain: null,
+    _mutable: null,
+    _placeholder: null,
+  }
+
+  const base: UnionValueShape<[NullValueShape, S]> = {
+    _type: "value" as const,
+    valueType: "union" as const,
+    shapes: [nullShape, shape] as [NullValueShape, S],
+    _plain: null as any,
+    _mutable: null as any,
+    _placeholder: null as any, // Default placeholder is null
+  }
+
+  return Object.assign(base, {
+    placeholder(
+      value: S["_placeholder"] | null,
+    ): UnionValueShape<[NullValueShape, S]> {
+      return { ...base, _placeholder: value } as UnionValueShape<
+        [NullValueShape, S]
+      >
+    },
+  })
+}
+
 /**
  * The LoroShape factory object
  *
@@ -386,7 +429,8 @@ export const Shape = {
   plain: {
     string: <T extends string = string>(
       ...options: T[]
-    ): WithPlaceholder<StringValueShape<T>> => {
+    ): WithPlaceholder<StringValueShape<T>> &
+      WithNullable<StringValueShape<T>> => {
       const base: StringValueShape<T> = {
         _type: "value" as const,
         valueType: "string" as const,
@@ -399,10 +443,16 @@ export const Shape = {
         placeholder(value: T): StringValueShape<T> {
           return { ...base, _placeholder: value }
         },
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, StringValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
       })
     },
 
-    number: (): WithPlaceholder<NumberValueShape> => {
+    number: (): WithPlaceholder<NumberValueShape> &
+      WithNullable<NumberValueShape> => {
       const base: NumberValueShape = {
         _type: "value" as const,
         valueType: "number" as const,
@@ -414,10 +464,16 @@ export const Shape = {
         placeholder(value: number): NumberValueShape {
           return { ...base, _placeholder: value }
         },
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, NumberValueShape]>
+        > {
+          return makeNullable(base)
+        },
       })
     },
 
-    boolean: (): WithPlaceholder<BooleanValueShape> => {
+    boolean: (): WithPlaceholder<BooleanValueShape> &
+      WithNullable<BooleanValueShape> => {
       const base: BooleanValueShape = {
         _type: "value" as const,
         valueType: "boolean" as const,
@@ -429,6 +485,11 @@ export const Shape = {
         placeholder(value: boolean): BooleanValueShape {
           return { ...base, _placeholder: value }
         },
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, BooleanValueShape]>
+        > {
+          return makeNullable(base)
+        },
       })
     },
 
@@ -470,46 +531,86 @@ export const Shape = {
      */
     struct: <T extends Record<string, ValueShape>>(
       shape: T,
-    ): StructValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "struct" as const,
-      shape,
-      _plain: {} as any,
-      _mutable: {} as any,
-      _placeholder: {} as any,
-    }),
+    ): StructValueShape<T> & WithNullable<StructValueShape<T>> => {
+      const base: StructValueShape<T> = {
+        _type: "value" as const,
+        valueType: "struct" as const,
+        shape,
+        _plain: {} as any,
+        _mutable: {} as any,
+        _placeholder: {} as any,
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, StructValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
 
     /**
      * @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> => ({
-      _type: "value" as const,
-      valueType: "struct" as const,
-      shape,
-      _plain: {} as any,
-      _mutable: {} as any,
-      _placeholder: {} as any,
-    }),
+    ): StructValueShape<T> & WithNullable<StructValueShape<T>> => {
+      const base: StructValueShape<T> = {
+        _type: "value" as const,
+        valueType: "struct" as const,
+        shape,
+        _plain: {} as any,
+        _mutable: {} as any,
+        _placeholder: {} as any,
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, StructValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
 
-    record: <T extends ValueShape>(shape: T): RecordValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "record" as const,
-      shape,
-      _plain: {} as any,
-      _mutable: {} as any,
-      _placeholder: {} as Record<string, never>,
-    }),
+    record: <T extends ValueShape>(
+      shape: T,
+    ): RecordValueShape<T> & WithNullable<RecordValueShape<T>> => {
+      const base: RecordValueShape<T> = {
+        _type: "value" as const,
+        valueType: "record" as const,
+        shape,
+        _plain: {} as any,
+        _mutable: {} as any,
+        _placeholder: {} as Record<string, never>,
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, RecordValueShape<T>]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
 
-    array: <T extends ValueShape>(shape: T): ArrayValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "array" as const,
-      shape,
-      _plain: [] as any,
-      _mutable: [] as any,
-      _placeholder: [] as never[],
-    }),
+    array: <T extends ValueShape>(
+      shape: T,
+    ): ArrayValueShape<T> & WithNullable<ArrayValueShape<T>> => {
+      const base: ArrayValueShape<T> = {
+        _type: "value" as const,
+        valueType: "array" as const,
+        shape,
+        _plain: [] as any,
+        _mutable: [] as any,
+        _placeholder: [] as never[],
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, ArrayValueShape<T>]>
+        > {
+          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?