@loro-extended/change 0.4.0 → 0.6.0

package/src/shape.ts

@@ -16,10 +16,11 @@ import type { MovableListDraftNode } from "./draft-nodes/movable-list.js"
 import type { RecordDraftNode } from "./draft-nodes/record.js"
 import type { TextDraftNode } from "./draft-nodes/text.js"
 
-export interface Shape<Plain, Draft> {
+export interface Shape<Plain, Draft, EmptyState = Plain> {
   readonly _type: string
   readonly _plain: Plain
   readonly _draft: Draft
+  readonly _emptyState: EmptyState
 }
 
 export interface DocShape<
@@ -29,30 +30,36 @@ export interface DocShape<
   >,
 > extends Shape<
     { [K in keyof NestedShapes]: NestedShapes[K]["_plain"] },
-    { [K in keyof NestedShapes]: NestedShapes[K]["_draft"] }
+    { [K in keyof NestedShapes]: NestedShapes[K]["_draft"] },
+    { [K in keyof NestedShapes]: NestedShapes[K]["_emptyState"] }
   > {
   readonly _type: "doc"
   // A doc's root containers each separately has its own shape, hence 'shapes'
   readonly shapes: NestedShapes
 }
 
-export interface TextContainerShape extends Shape<string, TextDraftNode> {
+export interface TextContainerShape
+  extends Shape<string, TextDraftNode, string> {
   readonly _type: "text"
 }
-export interface CounterContainerShape extends Shape<number, CounterDraftNode> {
+export interface CounterContainerShape
+  extends Shape<number, CounterDraftNode, number> {
   readonly _type: "counter"
 }
 export interface TreeContainerShape<NestedShape = ContainerOrValueShape>
-  extends Shape<any, any> {
+  extends Shape<any, any, never[]> {
   readonly _type: "tree"
   // TODO(duane): What does a tree contain? One type, or many?
   readonly shape: NestedShape
 }
 
 // Container schemas using interfaces for recursive references
+// NOTE: List and Record use never[] and Record<string, never> for EmptyState
+// to enforce that only empty values ([] and {}) are valid in empty state.
+// This prevents users from expecting per-entry merging behavior.
 export interface ListContainerShape<
   NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
-> extends Shape<NestedShape["_plain"][], ListDraftNode<NestedShape>> {
+> extends Shape<NestedShape["_plain"][], ListDraftNode<NestedShape>, never[]> {
   readonly _type: "list"
   // A list contains many elements, all of the same 'shape'
   readonly shape: NestedShape
@@ -60,7 +67,11 @@ export interface ListContainerShape<
 
 export interface MovableListContainerShape<
   NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
-> extends Shape<NestedShape["_plain"][], MovableListDraftNode<NestedShape>> {
+> extends Shape<
+    NestedShape["_plain"][],
+    MovableListDraftNode<NestedShape>,
+    never[]
+  > {
   readonly _type: "movableList"
   // A list contains many elements, all of the same 'shape'
   readonly shape: NestedShape
@@ -75,7 +86,8 @@ export interface MapContainerShape<
     { [K in keyof NestedShapes]: NestedShapes[K]["_plain"] },
     MapDraftNode<NestedShapes> & {
       [K in keyof NestedShapes]: NestedShapes[K]["_draft"]
-    }
+    },
+    { [K in keyof NestedShapes]: NestedShapes[K]["_emptyState"] }
   > {
   readonly _type: "map"
   // Each map property has its own shape, hence 'shapes'
@@ -86,7 +98,8 @@ export interface RecordContainerShape<
   NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
 > extends Shape<
     Record<string, NestedShape["_plain"]>,
-    RecordDraftNode<NestedShape>
+    RecordDraftNode<NestedShape>,
+    Record<string, never>
   > {
   readonly _type: "record"
   readonly shape: NestedShape
@@ -104,27 +117,31 @@ export type ContainerShape =
 export type ContainerType = ContainerShape["_type"]
 
 // LoroValue shape types - a shape for each of Loro's Value types
-export interface StringValueShape extends Shape<string, string> {
+export interface StringValueShape<T extends string = string>
+  extends Shape<T, T, T> {
   readonly _type: "value"
   readonly valueType: "string"
+  readonly options?: T[]
 }
-export interface NumberValueShape extends Shape<number, number> {
+export interface NumberValueShape extends Shape<number, number, number> {
   readonly _type: "value"
   readonly valueType: "number"
 }
-export interface BooleanValueShape extends Shape<boolean, boolean> {
+export interface BooleanValueShape extends Shape<boolean, boolean, boolean> {
   readonly _type: "value"
   readonly valueType: "boolean"
 }
-export interface NullValueShape extends Shape<null, null> {
+export interface NullValueShape extends Shape<null, null, null> {
   readonly _type: "value"
   readonly valueType: "null"
 }
-export interface UndefinedValueShape extends Shape<undefined, undefined> {
+export interface UndefinedValueShape
+  extends Shape<undefined, undefined, undefined> {
   readonly _type: "value"
   readonly valueType: "undefined"
 }
-export interface Uint8ArrayValueShape extends Shape<Uint8Array, Uint8Array> {
+export interface Uint8ArrayValueShape
+  extends Shape<Uint8Array, Uint8Array, Uint8Array> {
   readonly _type: "value"
   readonly valueType: "uint8array"
 }
@@ -133,34 +150,72 @@ export interface ObjectValueShape<
   T extends Record<string, ValueShape> = Record<string, ValueShape>,
 > extends Shape<
     { [K in keyof T]: T[K]["_plain"] },
-    { [K in keyof T]: T[K]["_draft"] }
+    { [K in keyof T]: T[K]["_draft"] },
+    { [K in keyof T]: T[K]["_emptyState"] }
   > {
   readonly _type: "value"
   readonly valueType: "object"
   readonly shape: T
 }
 
+// NOTE: RecordValueShape and ArrayValueShape use Record<string, never> and never[]
+// for EmptyState to enforce that only empty values ({} and []) are valid.
 export interface RecordValueShape<T extends ValueShape = ValueShape>
-  extends Shape<Record<string, T["_plain"]>, Record<string, T["_draft"]>> {
+  extends Shape<
+    Record<string, T["_plain"]>,
+    Record<string, T["_draft"]>,
+    Record<string, never>
+  > {
   readonly _type: "value"
   readonly valueType: "record"
   readonly shape: T
 }
 
 export interface ArrayValueShape<T extends ValueShape = ValueShape>
-  extends Shape<T["_plain"][], T["_draft"][]> {
+  extends Shape<T["_plain"][], T["_draft"][], never[]> {
   readonly _type: "value"
   readonly valueType: "array"
   readonly shape: T
 }
 
 export interface UnionValueShape<T extends ValueShape[] = ValueShape[]>
-  extends Shape<T[number]["_plain"], T[number]["_draft"]> {
+  extends Shape<
+    T[number]["_plain"],
+    T[number]["_draft"],
+    T[number]["_emptyState"]
+  > {
   readonly _type: "value"
   readonly valueType: "union"
   readonly shapes: T
 }
 
+/**
+ * A discriminated union shape that uses a discriminant key to determine which variant to use.
+ * This enables type-safe handling of tagged unions like:
+ *
+ * ```typescript
+ * type GamePresence =
+ *   | { type: "client"; name: string; input: { force: number; angle: number } }
+ *   | { type: "server"; cars: Record<string, CarState>; tick: number }
+ * ```
+ *
+ * @typeParam K - The discriminant key (e.g., "type")
+ * @typeParam T - A record mapping discriminant values to their object shapes
+ */
+export interface DiscriminatedUnionValueShape<
+  K extends string = string,
+  T extends Record<string, ObjectValueShape> = Record<string, ObjectValueShape>,
+> extends Shape<
+    T[keyof T]["_plain"],
+    T[keyof T]["_draft"],
+    T[keyof T]["_emptyState"]
+  > {
+  readonly _type: "value"
+  readonly valueType: "discriminatedUnion"
+  readonly discriminantKey: K
+  readonly variants: T
+}
+
 // Union of all ValueShapes - these can only contain other ValueShapes, not ContainerShapes
 export type ValueShape =
   | StringValueShape
@@ -173,6 +228,7 @@ export type ValueShape =
   | RecordValueShape
   | ArrayValueShape
   | UnionValueShape
+  | DiscriminatedUnionValueShape
 
 export type ContainerOrValueShape = ContainerShape | ValueShape
 
@@ -189,6 +245,7 @@ export const Shape = {
     shapes: shape,
     _plain: {} as any,
     _draft: {} as any,
+    _emptyState: {} as any,
   }),
 
   // CRDTs are represented by Loro Containers--they converge on state using Loro's
@@ -197,6 +254,7 @@ export const Shape = {
     _type: "counter" as const,
     _plain: 0,
     _draft: {} as CounterDraftNode,
+    _emptyState: 0,
   }),
 
   list: <T extends ContainerOrValueShape>(shape: T): ListContainerShape<T> => ({
@@ -204,6 +262,7 @@ export const Shape = {
     shape,
     _plain: [] as any,
     _draft: {} as any,
+    _emptyState: [] as never[],
   }),
 
   map: <T extends Record<string, ContainerOrValueShape>>(
@@ -213,6 +272,7 @@ export const Shape = {
     shapes: shape,
     _plain: {} as any,
     _draft: {} as any,
+    _emptyState: {} as any,
   }),
 
   record: <T extends ContainerOrValueShape>(
@@ -222,6 +282,7 @@ export const Shape = {
     shape,
     _plain: {} as any,
     _draft: {} as any,
+    _emptyState: {} as Record<string, never>,
   }),
 
   movableList: <T extends ContainerOrValueShape>(
@@ -231,12 +292,14 @@ export const Shape = {
     shape,
     _plain: [] as any,
     _draft: {} as any,
+    _emptyState: [] as never[],
   }),
 
   text: (): TextContainerShape => ({
     _type: "text" as const,
     _plain: "",
     _draft: {} as TextDraftNode,
+    _emptyState: "",
   }),
 
   tree: <T extends MapContainerShape>(shape: T): TreeContainerShape => ({
@@ -244,6 +307,7 @@ export const Shape = {
     shape,
     _plain: {} as any,
     _draft: {} as any,
+    _emptyState: [] as never[],
   }),
 
   // Values are represented as plain JS objects, with the limitation that they MUST be
@@ -251,11 +315,15 @@ export const Shape = {
   // "Last Write Wins", meaning there is no subtle convergent behavior here, just taking
   // the most recent value based on the current available information.
   plain: {
-    string: (): StringValueShape => ({
+    string: <T extends string = string>(
+      ...options: T[]
+    ): StringValueShape<T> => ({
       _type: "value" as const,
       valueType: "string" as const,
-      _plain: "",
-      _draft: "",
+      _plain: (options[0] ?? "") as T,
+      _draft: (options[0] ?? "") as T,
+      _emptyState: (options[0] ?? "") as T,
+      options: options.length > 0 ? options : undefined,
     }),
 
     number: (): NumberValueShape => ({
@@ -263,6 +331,7 @@ export const Shape = {
       valueType: "number" as const,
       _plain: 0,
       _draft: 0,
+      _emptyState: 0,
     }),
 
     boolean: (): BooleanValueShape => ({
@@ -270,6 +339,7 @@ export const Shape = {
       valueType: "boolean" as const,
       _plain: false,
       _draft: false,
+      _emptyState: false,
     }),
 
     null: (): NullValueShape => ({
@@ -277,6 +347,7 @@ export const Shape = {
       valueType: "null" as const,
       _plain: null,
       _draft: null,
+      _emptyState: null,
     }),
 
     undefined: (): UndefinedValueShape => ({
@@ -284,6 +355,7 @@ export const Shape = {
       valueType: "undefined" as const,
       _plain: undefined,
       _draft: undefined,
+      _emptyState: undefined,
     }),
 
     uint8Array: (): Uint8ArrayValueShape => ({
@@ -291,6 +363,7 @@ export const Shape = {
       valueType: "uint8array" as const,
       _plain: new Uint8Array(),
       _draft: new Uint8Array(),
+      _emptyState: new Uint8Array(),
     }),
 
     object: <T extends Record<string, ValueShape>>(
@@ -301,6 +374,7 @@ export const Shape = {
       shape,
       _plain: {} as any,
       _draft: {} as any,
+      _emptyState: {} as any,
     }),
 
     record: <T extends ValueShape>(shape: T): RecordValueShape<T> => ({
@@ -309,6 +383,7 @@ export const Shape = {
       shape,
       _plain: {} as any,
       _draft: {} as any,
+      _emptyState: {} as Record<string, never>,
     }),
 
     array: <T extends ValueShape>(shape: T): ArrayValueShape<T> => ({
@@ -317,6 +392,7 @@ export const Shape = {
       shape,
       _plain: [] as any,
       _draft: [] as any,
+      _emptyState: [] as never[],
     }),
 
     // Special value type that helps make things like `string | null` representable
@@ -327,6 +403,49 @@ export const Shape = {
       shapes,
       _plain: {} as any,
       _draft: {} as any,
+      _emptyState: {} as any,
+    }),
+
+    /**
+     * Creates a discriminated union shape for type-safe tagged unions.
+     *
+     * @example
+     * ```typescript
+     * const ClientPresenceShape = Shape.plain.object({
+     *   type: Shape.plain.string("client"),
+     *   name: Shape.plain.string(),
+     *   input: Shape.plain.object({ force: Shape.plain.number(), angle: Shape.plain.number() }),
+     * })
+     *
+     * const ServerPresenceShape = Shape.plain.object({
+     *   type: Shape.plain.string("server"),
+     *   cars: Shape.plain.record(Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() })),
+     *   tick: Shape.plain.number(),
+     * })
+     *
+     * const GamePresenceSchema = Shape.plain.discriminatedUnion("type", {
+     *   client: ClientPresenceShape,
+     *   server: ServerPresenceShape,
+     * })
+     * ```
+     *
+     * @param discriminantKey - The key used to discriminate between variants (e.g., "type")
+     * @param variants - A record mapping discriminant values to their object shapes
+     */
+    discriminatedUnion: <
+      K extends string,
+      T extends Record<string, ObjectValueShape>,
+    >(
+      discriminantKey: K,
+      variants: T,
+    ): DiscriminatedUnionValueShape<K, T> => ({
+      _type: "value" as const,
+      valueType: "discriminatedUnion" as const,
+      discriminantKey,
+      variants,
+      _plain: {} as any,
+      _draft: {} as any,
+      _emptyState: {} as any,
     }),
   },
 }

package/src/string-literal.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest"
+import { Shape } from "./shape.js"
+import { validateValue } from "./validation.js"
+
+describe("String Literal Shape", () => {
+  it("should support type inference for string unions", () => {
+    const schema = Shape.plain.string<"user" | "ai">()
+
+    // This is a type-level check, we can't easily assert it at runtime without options
+    // But we can check that it validates strings
+    expect(validateValue("user", schema)).toBe("user")
+    expect(validateValue("ai", schema)).toBe("ai")
+    expect(validateValue("other", schema)).toBe("other") // No runtime validation without options
+  })
+
+  it("should support runtime validation when options are provided", () => {
+    const schema = Shape.plain.string("user", "ai")
+
+    expect(validateValue("user", schema)).toBe("user")
+    expect(validateValue("ai", schema)).toBe("ai")
+
+    expect(() => validateValue("other", schema)).toThrow(
+      'Expected one of [user, ai] at path root, got "other"',
+    )
+  })
+
+  it("should work with single option", () => {
+    const schema = Shape.plain.string("fixed")
+
+    expect(validateValue("fixed", schema)).toBe("fixed")
+    expect(() => validateValue("other", schema)).toThrow(
+      'Expected one of [fixed] at path root, got "other"',
+    )
+  })
+
+  it("should maintain backward compatibility", () => {
+    const schema = Shape.plain.string()
+
+    expect(validateValue("any", schema)).toBe("any")
+    expect(validateValue("", schema)).toBe("")
+  })
+})

package/src/types.ts

@@ -6,9 +6,19 @@
 import type { ContainerShape, DocShape, Shape } from "./shape.js"
 
 // Input type inference - what developers can pass to push/insert methods
-export type InferPlainType<T> = T extends Shape<infer P, any> ? P : never
+export type InferPlainType<T> = T extends Shape<infer P, any, any> ? P : never
 
-export type InferDraftType<T> = T extends Shape<any, infer D> ? D : never
+export type InferDraftType<T> = T extends Shape<any, infer D, any> ? D : never
+
+/**
+ * Extracts the valid empty state type from a shape.
+ *
+ * For dynamic containers (list, record, etc.), this will be constrained to
+ * empty values ([] or {}) to prevent users from expecting per-entry merging.
+ */
+export type InferEmptyStateType<T> = T extends Shape<any, any, infer E>
+  ? E
+  : never
 
 // Draft-specific type inference that properly handles the draft context
 export type Draft<T extends DocShape<Record<string, ContainerShape>>> =

package/src/validation.ts

@@ -8,6 +8,7 @@ import type {
   ObjectValueShape,
   RecordContainerShape,
   RecordValueShape,
+  StringValueShape,
   UnionValueShape,
   ValueShape,
 } from "./shape.js"
@@ -108,13 +109,20 @@ export function validateValue(
     const valueSchema = schema as ValueShape
 
     switch (valueSchema.valueType) {
-      case "string":
+      case "string": {
         if (typeof value !== "string") {
           throw new Error(
             `Expected string at path ${currentPath}, got ${typeof value}`,
           )
         }
+        const stringSchema = valueSchema as StringValueShape
+        if (stringSchema.options && !stringSchema.options.includes(value)) {
+          throw new Error(
+            `Expected one of [${stringSchema.options.join(", ")}] at path ${currentPath}, got "${value}"`,
+          )
+        }
         return value
+      }
 
       case "number":
         if (typeof value !== "number") {