@loro-extended/change 0.2.0

package/src/schema.fixtures.ts

@@ -0,0 +1,138 @@
+import { Shape } from "./shape.js"
+
+const crdt = Shape
+const value = Shape.plain
+
+// Pattern 1: List with POJO objects (leaf nodes)
+export const simpleList = crdt.list(value.object({ title: value.string() }))
+
+// Pattern 2: List with LoroMap containers
+export const containerListDoc = Shape.doc({
+  title: crdt.text(),
+  list: crdt.list(
+    crdt.map({
+      title: value.string(),
+      tags: value.array(value.string()),
+    }),
+  ),
+})
+
+// Pattern 3: Fully nested containers
+export const deeplyNested = crdt.list(
+  crdt.map({
+    title: value.string(),
+    tags: crdt.list(value.string()), // LoroList of strings, not array
+  }),
+)
+
+// Example: Complex document schema with deeply nested Loro and POJO types
+export const complexDocSchema = Shape.doc({
+  // Simple Loro containers
+  title: crdt.text(),
+  viewCount: crdt.counter(),
+
+  // Mixed content: LoroList containing POJO objects
+  articles: crdt.list(
+    value.object({
+      id: value.string(),
+      title: value.string(),
+      publishedAt: value.string(),
+      tags: value.array(value.string()), // POJO array (leaf node)
+      metadata: value.object({
+        wordCount: value.number(),
+        readingTime: value.number(),
+        featured: value.boolean(),
+      }),
+    }),
+  ),
+
+  // LoroMovableList for reorderable content
+  priorityTasks: crdt.movableList(
+    value.object({
+      id: value.string(),
+      title: value.string(),
+      priority: value.number(),
+      completed: value.boolean(),
+    }),
+  ),
+
+  // Deeply nested: LoroList containing LoroMap containers
+  collaborativeArticles: crdt.list(
+    crdt.map({
+      // Each article is a LoroMap with mixed content
+      title: crdt.text(), // Collaborative text editing
+      content: crdt.text(), // Collaborative content editing
+
+      // POJO metadata (leaf nodes)
+      publishedAt: value.string(),
+      authorId: value.string(),
+
+      // Nested LoroMovableList for reorderable collaborative tag management
+      tags: crdt.movableList(value.string()),
+
+      // Even deeper nesting: LoroList of LoroMap for comments
+      comments: crdt.list(
+        crdt.map({
+          id: value.string(), // POJO leaf
+          authorId: value.string(), // POJO leaf
+          content: crdt.text(), // Collaborative comment editing
+          timestamp: value.string(), // POJO leaf
+
+          // Nested replies as LoroMovableList of POJO objects
+          replies: crdt.movableList(
+            value.object({
+              id: value.string(),
+              authorId: value.string(),
+              content: value.string(), // Non-collaborative reply content
+              timestamp: value.string(),
+            }),
+          ),
+        }),
+      ),
+    }),
+  ),
+
+  // Complex metadata structure
+  siteMetadata: crdt.map({
+    // POJO configuration
+    config: value.object({
+      siteName: value.string(),
+      baseUrl: value.string(),
+      theme: value.string(),
+    }),
+
+    // Collaborative analytics
+    analytics: crdt.map({
+      totalViews: crdt.counter(),
+      uniqueVisitors: crdt.counter(),
+
+      // Daily stats as LoroMovableList of POJO objects (reorderable by date)
+      dailyStats: crdt.movableList(
+        value.object({
+          date: value.string(),
+          views: value.number(),
+          visitors: value.number(),
+          bounceRate: value.number(),
+        }),
+      ),
+    }),
+
+    // Collaborative feature flags
+    features: crdt.map({
+      commentsEnabled: value.boolean(),
+      darkModeEnabled: value.boolean(),
+
+      // Nested collaborative settings
+      moderationSettings: crdt.map({
+        autoModeration: value.boolean(),
+        bannedWords: crdt.movableList(value.string()), // Reorderable banned words
+        moderators: crdt.list(
+          value.object({
+            userId: value.string(),
+            rules: value.array(value.string()),
+          }),
+        ),
+      }),
+    }),
+  }),
+})

package/src/shape.ts

@@ -0,0 +1,348 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: required
+
+import type {
+  LoroCounter,
+  LoroList,
+  LoroMap,
+  LoroMovableList,
+  LoroText,
+  LoroTree,
+} from "loro-crdt"
+
+import type { CounterDraftNode } from "./draft-nodes/counter.js"
+import type { ListDraftNode } from "./draft-nodes/list.js"
+import type { MapDraftNode } from "./draft-nodes/map.js"
+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> {
+  readonly _type: string
+  readonly _plain: Plain
+  readonly _draft: Draft
+}
+
+export interface DocShape<
+  NestedShapes extends Record<string, ContainerShape> = Record<
+    string,
+    ContainerShape
+  >,
+> extends Shape<
+    { [K in keyof NestedShapes]: NestedShapes[K]["_plain"] },
+    { [K in keyof NestedShapes]: NestedShapes[K]["_draft"] }
+  > {
+  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> {
+  readonly _type: "text"
+}
+export interface CounterContainerShape extends Shape<number, CounterDraftNode> {
+  readonly _type: "counter"
+}
+export interface TreeContainerShape<NestedShape = ContainerOrValueShape>
+  extends Shape<any, any> {
+  readonly _type: "tree"
+  // TODO(duane): What does a tree contain? One type, or many?
+  readonly shape: NestedShape
+}
+
+// Container schemas using interfaces for recursive references
+export interface ListContainerShape<
+  NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
+> extends Shape<NestedShape["_plain"][], ListDraftNode<NestedShape>> {
+  readonly _type: "list"
+  // A list contains many elements, all of the same 'shape'
+  readonly shape: NestedShape
+}
+
+export interface MovableListContainerShape<
+  NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
+> extends Shape<NestedShape["_plain"][], MovableListDraftNode<NestedShape>> {
+  readonly _type: "movableList"
+  // A list contains many elements, all of the same 'shape'
+  readonly shape: NestedShape
+}
+
+export interface MapContainerShape<
+  NestedShapes extends Record<string, ContainerOrValueShape> = Record<
+    string,
+    ContainerOrValueShape
+  >,
+> extends Shape<
+    { [K in keyof NestedShapes]: NestedShapes[K]["_plain"] },
+    MapDraftNode<NestedShapes> & {
+      [K in keyof NestedShapes]: NestedShapes[K]["_draft"]
+    }
+  > {
+  readonly _type: "map"
+  // Each map property has its own shape, hence 'shapes'
+  readonly shapes: NestedShapes
+}
+
+export interface RecordContainerShape<
+  NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
+> extends Shape<
+    Record<string, NestedShape["_plain"]>,
+    RecordDraftNode<NestedShape>
+  > {
+  readonly _type: "record"
+  readonly shape: NestedShape
+}
+
+export type ContainerShape =
+  | CounterContainerShape
+  | ListContainerShape
+  | MapContainerShape
+  | MovableListContainerShape
+  | RecordContainerShape
+  | TextContainerShape
+  | TreeContainerShape
+
+export type ContainerType = ContainerShape["_type"]
+
+// LoroValue shape types - a shape for each of Loro's Value types
+export interface StringValueShape extends Shape<string, string> {
+  readonly _type: "value"
+  readonly valueType: "string"
+}
+export interface NumberValueShape extends Shape<number, number> {
+  readonly _type: "value"
+  readonly valueType: "number"
+}
+export interface BooleanValueShape extends Shape<boolean, boolean> {
+  readonly _type: "value"
+  readonly valueType: "boolean"
+}
+export interface NullValueShape extends Shape<null, null> {
+  readonly _type: "value"
+  readonly valueType: "null"
+}
+export interface UndefinedValueShape extends Shape<undefined, undefined> {
+  readonly _type: "value"
+  readonly valueType: "undefined"
+}
+export interface Uint8ArrayValueShape extends Shape<Uint8Array, Uint8Array> {
+  readonly _type: "value"
+  readonly valueType: "uint8array"
+}
+
+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"] }
+  > {
+  readonly _type: "value"
+  readonly valueType: "object"
+  readonly shape: T
+}
+
+export interface RecordValueShape<T extends ValueShape = ValueShape>
+  extends Shape<Record<string, T["_plain"]>, Record<string, T["_draft"]>> {
+  readonly _type: "value"
+  readonly valueType: "record"
+  readonly shape: T
+}
+
+export interface ArrayValueShape<T extends ValueShape = ValueShape>
+  extends Shape<T["_plain"][], T["_draft"][]> {
+  readonly _type: "value"
+  readonly valueType: "array"
+  readonly shape: T
+}
+
+export interface UnionValueShape<T extends ValueShape[] = ValueShape[]>
+  extends Shape<T[number]["_plain"], T[number]["_draft"]> {
+  readonly _type: "value"
+  readonly valueType: "union"
+  readonly shapes: T
+}
+
+// Union of all ValueShapes - these can only contain other ValueShapes, not ContainerShapes
+export type ValueShape =
+  | StringValueShape
+  | NumberValueShape
+  | BooleanValueShape
+  | NullValueShape
+  | UndefinedValueShape
+  | Uint8ArrayValueShape
+  | ObjectValueShape
+  | RecordValueShape
+  | ArrayValueShape
+  | UnionValueShape
+
+export type ContainerOrValueShape = ContainerShape | ValueShape
+
+/**
+ * The LoroShape factory object
+ *
+ * If a container has a `shape` type variable, it refers to the shape it contains--
+ * so for example, a `LoroShape.list(LoroShape.text())` would return a value of type
+ * `ListContainerShape<TextContainerShape>`.
+ */
+export const Shape = {
+  doc: <T extends Record<string, ContainerShape>>(shape: T): DocShape<T> => ({
+    _type: "doc" as const,
+    shapes: shape,
+    _plain: {} as any,
+    _draft: {} as any,
+  }),
+
+  // CRDTs are represented by Loro Containers--they converge on state using Loro's
+  // various CRDT algorithms
+  counter: (): CounterContainerShape => ({
+    _type: "counter" as const,
+    _plain: 0,
+    _draft: {} as CounterDraftNode,
+  }),
+
+  list: <T extends ContainerOrValueShape>(shape: T): ListContainerShape<T> => ({
+    _type: "list" as const,
+    shape,
+    _plain: [] as any,
+    _draft: {} as any,
+  }),
+
+  map: <T extends Record<string, ContainerOrValueShape>>(
+    shape: T,
+  ): MapContainerShape<T> => ({
+    _type: "map" as const,
+    shapes: shape,
+    _plain: {} as any,
+    _draft: {} as any,
+  }),
+
+  record: <T extends ContainerOrValueShape>(
+    shape: T,
+  ): RecordContainerShape<T> => ({
+    _type: "record" as const,
+    shape,
+    _plain: {} as any,
+    _draft: {} as any,
+  }),
+
+  movableList: <T extends ContainerOrValueShape>(
+    shape: T,
+  ): MovableListContainerShape<T> => ({
+    _type: "movableList" as const,
+    shape,
+    _plain: [] as any,
+    _draft: {} as any,
+  }),
+
+  text: (): TextContainerShape => ({
+    _type: "text" as const,
+    _plain: "",
+    _draft: {} as TextDraftNode,
+  }),
+
+  tree: <T extends MapContainerShape>(shape: T): TreeContainerShape => ({
+    _type: "tree" as const,
+    shape,
+    _plain: {} as any,
+    _draft: {} as any,
+  }),
+
+  // Values are represented as plain JS objects, with the limitation that they MUST be
+  // representable as a Loro "Value"--basically JSON. The behavior of a Value is basically
+  // "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 => ({
+      _type: "value" as const,
+      valueType: "string" as const,
+      _plain: "",
+      _draft: "",
+    }),
+
+    number: (): NumberValueShape => ({
+      _type: "value" as const,
+      valueType: "number" as const,
+      _plain: 0,
+      _draft: 0,
+    }),
+
+    boolean: (): BooleanValueShape => ({
+      _type: "value" as const,
+      valueType: "boolean" as const,
+      _plain: false,
+      _draft: false,
+    }),
+
+    null: (): NullValueShape => ({
+      _type: "value" as const,
+      valueType: "null" as const,
+      _plain: null,
+      _draft: null,
+    }),
+
+    undefined: (): UndefinedValueShape => ({
+      _type: "value" as const,
+      valueType: "undefined" as const,
+      _plain: undefined,
+      _draft: undefined,
+    }),
+
+    uint8Array: (): Uint8ArrayValueShape => ({
+      _type: "value" as const,
+      valueType: "uint8array" as const,
+      _plain: new Uint8Array(),
+      _draft: new Uint8Array(),
+    }),
+
+    object: <T extends Record<string, ValueShape>>(
+      shape: T,
+    ): ObjectValueShape<T> => ({
+      _type: "value" as const,
+      valueType: "object" as const,
+      shape,
+      _plain: {} as any,
+      _draft: {} as any,
+    }),
+
+    record: <T extends ValueShape>(shape: T): RecordValueShape<T> => ({
+      _type: "value" as const,
+      valueType: "record" as const,
+      shape,
+      _plain: {} as any,
+      _draft: {} as any,
+    }),
+
+    array: <T extends ValueShape>(shape: T): ArrayValueShape<T> => ({
+      _type: "value" as const,
+      valueType: "array" as const,
+      shape,
+      _plain: [] as any,
+      _draft: [] as any,
+    }),
+
+    // Special value type that helps make things like `string | null` representable
+    // TODO(duane): should this be a more general type for containers too?
+    union: <T extends ValueShape[]>(shapes: T): UnionValueShape<T> => ({
+      _type: "value" as const,
+      valueType: "union" as const,
+      shapes,
+      _plain: {} as any,
+      _draft: {} as any,
+    }),
+  },
+}
+
+// Add this type mapping near the top of your file, after the imports
+export type ShapeToContainer<T extends DocShape | ContainerShape> =
+  T extends TextContainerShape
+    ? LoroText
+    : T extends CounterContainerShape
+      ? LoroCounter
+      : T extends ListContainerShape
+        ? LoroList
+        : T extends MovableListContainerShape
+          ? LoroMovableList
+          : T extends MapContainerShape | RecordContainerShape
+            ? LoroMap
+            : T extends TreeContainerShape
+              ? LoroTree
+              : never // not a container

package/src/types.ts

@@ -0,0 +1,15 @@
+/* =============================================================================
+ * UNIFIED BASE SCHEMA MAPPER SYSTEM
+ * =============================================================================
+ */
+
+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 InferDraftType<T> = T extends Shape<any, infer D> ? D : never
+
+// Draft-specific type inference that properly handles the draft context
+export type Draft<T extends DocShape<Record<string, ContainerShape>>> =
+  InferDraftType<T>

package/src/utils/type-guards.ts

@@ -0,0 +1,210 @@
+import type {
+  Container,
+  LoroCounter,
+  LoroList,
+  LoroMap,
+  LoroMovableList,
+  LoroText,
+  LoroTree,
+  LoroTreeNode,
+  Value,
+} from "loro-crdt"
+import type {
+  ContainerOrValueShape,
+  ContainerShape,
+  CounterContainerShape,
+  ListContainerShape,
+  MapContainerShape,
+  MovableListContainerShape,
+  RecordContainerShape,
+  TextContainerShape,
+  TreeContainerShape,
+  ValueShape,
+} from "../shape.js"
+
+export { isContainer, isContainerId } from "loro-crdt"
+
+/**
+ * Type guard to check if a container is a LoroCounter
+ */
+export function isLoroCounter(container: Container): container is LoroCounter {
+  return container.kind() === "Counter"
+}
+
+/**
+ * Type guard to check if a container is a LoroList
+ */
+export function isLoroList(container: Container): container is LoroList {
+  return container.kind() === "List"
+}
+
+/**
+ * Type guard to check if a container is a LoroMap
+ */
+export function isLoroMap(container: Container): container is LoroMap {
+  return container.kind() === "Map"
+}
+
+/**
+ * Type guard to check if a container is a LoroMovableList
+ */
+export function isLoroMovableList(
+  container: Container,
+): container is LoroMovableList {
+  return container.kind() === "MovableList"
+}
+
+/**
+ * Type guard to check if a container is a LoroText
+ */
+export function isLoroText(container: Container): container is LoroText {
+  return container.kind() === "Text"
+}
+
+/**
+ * Type guard to check if a container is a LoroTree
+ */
+export function isLoroTree(container: Container): container is LoroTree {
+  return container.kind() === "Tree"
+}
+
+/**
+ * Type guard to check if an object is a LoroTreeNode
+ * Note: LoroTreeNode is not a Container, so we check for its specific properties
+ */
+export function isLoroTreeNode(obj: any): obj is LoroTreeNode {
+  return (
+    obj &&
+    typeof obj === "object" &&
+    typeof obj.id === "string" &&
+    typeof obj.data === "object" &&
+    typeof obj.parent === "function" &&
+    typeof obj.children === "function" &&
+    typeof obj.createNode === "function"
+  )
+}
+
+/**
+ * Type guard to ensure cached container matches expected type using kind() method
+ */
+export function assertContainerType<T extends Container>(
+  cached: Container,
+  expected: T,
+  context: string = "container operation",
+): asserts cached is T {
+  if (cached.kind() !== expected.kind()) {
+    throw new Error(
+      `Type safety violation in ${context}: ` +
+        `cached container kind '${cached.kind()}' does not match ` +
+        `expected kind '${expected.kind()}'`,
+    )
+  }
+
+  // Additional safety check: ensure IDs match
+  if (cached.id !== expected.id) {
+    throw new Error(
+      `Container ID mismatch in ${context}: ` +
+        `cached ID '${cached.id}' does not match expected ID '${expected.id}'`,
+    )
+  }
+}
+
+/**
+ * Type guard to check if a schema is for TextDraftNode
+ */
+export function isTextShape(
+  schema: ContainerOrValueShape,
+): schema is TextContainerShape {
+  return schema && typeof schema === "object" && schema._type === "text"
+}
+
+/**
+ * Type guard to check if a schema is for CounterDraftNode
+ */
+export function isCounterShape(
+  schema: ContainerOrValueShape,
+): schema is CounterContainerShape {
+  return schema && typeof schema === "object" && schema._type === "counter"
+}
+
+/**
+ * Type guard to check if a schema is for ListDraftNode
+ */
+export function isListShape(
+  schema: ContainerOrValueShape,
+): schema is ListContainerShape {
+  return schema && typeof schema === "object" && schema._type === "list"
+}
+
+/**
+ * Type guard to check if a schema is for MovableListDraftNode
+ */
+export function isMovableListShape(
+  schema: ContainerOrValueShape,
+): schema is MovableListContainerShape {
+  return schema && typeof schema === "object" && schema._type === "movableList"
+}
+
+/**
+ * Type guard to check if a schema is for MapDraftNode
+ */
+export function isMapShape(
+  schema: ContainerOrValueShape,
+): schema is MapContainerShape {
+  return schema && typeof schema === "object" && schema._type === "map"
+}
+
+/**
+ * Type guard to check if a schema is for RecordDraftNode
+ */
+export function isRecordShape(
+  schema: ContainerOrValueShape,
+): schema is RecordContainerShape {
+  return schema && typeof schema === "object" && schema._type === "record"
+}
+
+/**
+ * Type guard to check if a schema is for TreeDraftNode
+ */
+export function isTreeShape(
+  schema: ContainerOrValueShape,
+): schema is TreeContainerShape {
+  return schema && typeof schema === "object" && schema._type === "tree"
+}
+
+export function isContainerShape(
+  schema: ContainerOrValueShape,
+): schema is ContainerShape {
+  return schema._type && schema._type !== "value"
+}
+
+/**
+ * Type guard to check if a schema is any of the Value shapes
+ */
+export function isValueShape(
+  schema: ContainerOrValueShape,
+): schema is ValueShape {
+  return (
+    schema._type === "value" &&
+    [
+      "string",
+      "number",
+      "boolean",
+      "null",
+      "undefined",
+      "uint8array",
+      "object",
+      "record",
+      "array",
+    ].includes(schema.valueType)
+  )
+}
+
+export function isObjectValue(value: Value): value is { [key: string]: Value } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof Uint8Array)
+  )
+}