loro-crdt - npm Package Compare versions

Comparing version 0.13.1 to 0.14.0

dist/loro.d.ts

@@ -1,2 +0,2 @@
-import { ContainerID, Container, Value, TreeID, OpId, Delta, LoroText, LoroMap, LoroTree, LoroList } from 'loro-wasm';
+import { Container, ContainerID, TreeID, OpId, Delta, Value, LoroText, LoroMap, LoroTree, LoroList } from 'loro-wasm';
 export * from 'loro-wasm';
@@ -16,3 +16,3 @@ export { Loro } from 'loro-wasm';
  *
- * @prop local - Indicates whether the event is local.
+ * @prop by - How the event is triggered.
  * @prop origin - (Optional) Provides information about the origin of the event.
@@ -24,7 +24,10 @@ * @prop diff - Contains the differential information related to the event.
 interface LoroEventBatch {
-    local: boolean;
     /**
-     * If true, this event was triggered by a checkout.
+     * How the event is triggered.
+     *
+     * - `local`: The event is triggered by a local transaction.
+     * - `import`: The event is triggered by an import operation.
+     * - `checkout`: The event is triggered by a checkout operation.
      */
-    fromCheckout: boolean;
+    by: "local" | "import" | "checkout";
     origin?: string;
@@ -125,17 +128,117 @@ /**
     }
-    interface Loro<T extends Record<string, any> = Record<string, any>> {
-        getTypedMap<Key extends keyof T & string>(name: Key): T[Key] extends LoroMap ? T[Key] : never;
-        getTypedList<Key extends keyof T & string>(name: Key): T[Key] extends LoroList ? T[Key] : never;
-        getMap(key: string | ContainerID): LoroMap<T[string]>;
-        getList(key: string | ContainerID): LoroList<T[string]>;
-        getTree(key: string | ContainerID): LoroTree<T[string]>;
+    interface Loro<T extends Record<string, Container> = Record<string, Container>> {
+        /**
+         * Get a LoroMap by container id
+         *
+         * The object returned is a new js object each time because it need to cross
+         * the WASM boundary.
+         *
+         * @example
+         * ```ts
+         * import { Loro } from "loro-crdt";
+         *
+         * const doc = new Loro();
+         * const map = doc.getMap("map");
+         * ```
+         */
+        getMap<Key extends keyof T>(name: Key): T[Key] extends LoroMap ? T[Key] : LoroMap;
+        /**
+         * Get a LoroList by container id
+         *
+         * The object returned is a new js object each time because it need to cross
+         * the WASM boundary.
+         *
+         * @example
+         * ```ts
+         * import { Loro } from "loro-crdt";
+         *
+         * const doc = new Loro();
+         * const list = doc.getList("list");
+         * ```
+         */
+        getList<Key extends keyof T>(name: Key): T[Key] extends LoroList ? T[Key] : LoroList;
+        /**
+         * Get a LoroTree by container id
+         *
+         *  The object returned is a new js object each time because it need to cross
+         *  the WASM boundary.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const tree = doc.getTree("tree");
+         *  ```
+         */
+        getTree<Key extends keyof T>(name: Key): T[Key] extends LoroTree ? T[Key] : LoroTree;
         getText(key: string | ContainerID): LoroText;
     }
-    interface LoroList<T extends any[] = any[]> {
+    interface LoroList<T = unknown> {
         new (): LoroList<T>;
-        insertContainer<C extends Container>(pos: number, child: C): C;
-        get(index: number): undefined | Value | Container;
-        getTyped<Key extends keyof T & number>(loro: Loro, index: Key): T[Key];
-        insertTyped<Key extends keyof T & number>(pos: Key, value: T[Key]): void;
-        insert(pos: number, value: Value): void;
+        /**
+         *  Get elements of the list. If the value is a child container, the corresponding
+         *  `Container` will be returned.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const list = doc.getList("list");
+         *  list.insert(0, 100);
+         *  list.insert(1, "foo");
+         *  list.insert(2, true);
+         *  list.insertContainer(3, new LoroText());
+         *  console.log(list.value);  // [100, "foo", true, LoroText];
+         *  ```
+         */
+        toArray(): T[];
+        /**
+         * Insert a container at the index.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const list = doc.getList("list");
+         *  list.insert(0, 100);
+         *  const text = list.insertContainer(1, new LoroText());
+         *  text.insert(0, "Hello");
+         *  console.log(list.getDeepValue());  // [100, "Hello"];
+         *  ```
+         */
+        insertContainer<C extends Container>(pos: number, child: C): T extends C ? T : C;
+        /**
+         * Get the value at the index. If the value is a container, the corresponding handler will be returned.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const list = doc.getList("list");
+         *  list.insert(0, 100);
+         *  console.log(list.get(0));  // 100
+         *  console.log(list.get(1));  // undefined
+         *  ```
+         */
+        get(index: number): T;
+        /**
+         *  Insert a value at index.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const list = doc.getList("list");
+         *  list.insert(0, 100);
+         *  list.insert(1, "foo");
+         *  list.insert(2, true);
+         *  console.log(list.value);  // [100, "foo", true];
+         *  ```
+         */
+        insert(pos: number, value: Exclude<T, Container>): void;
         delete(pos: number, len: number): void;
@@ -145,10 +248,70 @@ subscribe(txn: Loro, listener: Listener): number;
     }
-    interface LoroMap<T extends Record<string, any> = Record<string, any>> {
+    interface LoroMap<T extends Record<string, unknown> = Record<string, unknown>> {
         new (): LoroMap<T>;
+        /**
+         *  Get the value of the key. If the value is a child container, the corresponding
+         *  `Container` will be returned.
+         *
+         *  The object returned is a new js object each time because it need to cross
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const map = doc.getMap("map");
+         *  map.set("foo", "bar");
+         *  const bar = map.get("foo");
+         *  ```
+         */
         getOrCreateContainer<C extends Container>(key: string, child: C): C;
-        setContainer<C extends Container>(key: string, child: C): C;
-        get(key: string): undefined | Value | Container;
-        getTyped<Key extends keyof T & string>(txn: Loro, key: Key): T[Key];
-        set(key: string, value: Value): void;
-        setTyped<Key extends keyof T & string>(key: Key, value: T[Key]): void;
+        /**
+         * Set the key with a container.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const map = doc.getMap("map");
+         *  map.set("foo", "bar");
+         *  const text = map.setContainer("text", new LoroText());
+         *  const list = map.setContainer("list", new LoroText());
+         *  ```
+         */
+        setContainer<C extends Container, Key extends keyof T>(key: Key, child: C): NonNullableType<T[Key]> extends C ? NonNullableType<T[Key]> : C;
+        /**
+         *  Get the value of the key. If the value is a child container, the corresponding
+         *  `Container` will be returned.
+         *
+         *  The object/value returned is a new js object/value each time because it need to cross
+         *  the WASM boundary.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const map = doc.getMap("map");
+         *  map.set("foo", "bar");
+         *  const bar = map.get("foo");
+         *  ```
+         */
+        get<Key extends keyof T>(key: Key): T[Key];
+        /**
+         * Set the key with the value.
+         *
+         *  If the value of the key is exist, the old value will be updated.
+         *
+         *  @example
+         *  ```ts
+         *  import { Loro } from "loro-crdt";
+         *
+         *  const doc = new Loro();
+         *  const map = doc.getMap("map");
+         *  map.set("foo", "bar");
+         *  map.set("foo", "baz");
+         *  ```
+         */
+        set<Key extends keyof T>(key: Key, value: Exclude<T[Key], Container>): void;
         delete(key: string): void;
@@ -163,3 +326,3 @@ subscribe(txn: Loro, listener: Listener): number;
     }
-    interface LoroTree<T extends Record<string, any> = Record<string, any>> {
+    interface LoroTree<T extends Record<string, unknown> = Record<string, unknown>> {
         new (): LoroTree<T>;
@@ -173,3 +336,6 @@ createNode(parent: TreeID | undefined): LoroTreeNode<T>;
     }
-    interface LoroTreeNode<T extends Record<string, any> = Record<string, any>> {
+    interface LoroTreeNode<T extends Record<string, unknown> = Record<string, unknown>> {
+        /**
+         * Get the associated metadata map container of a tree node.
+         */
         readonly data: LoroMap<T>;
@@ -179,7 +345,8 @@ createNode(): LoroTreeNode<T>;
         moveTo(parent: LoroTreeNode<T>): void;
-        parent(): LoroTreeNode | undefined;
+        parent(): LoroTreeNode<T> | undefined;
         children(): Array<LoroTreeNode<T>>;
     }
 }
+type NonNullableType<T> = Exclude<T, null | undefined>;
 
 export { Diff, Frontiers, ListDiff, LoroEvent, LoroEventBatch, MapDiff, Path, TextDiff, TreeDiff, TreeDiffItem, getType, isContainer, isContainerId };

dist/loro.js

@@ -5,30 +5,2 @@ 'use strict';
 
-loroWasm.Loro.prototype.getTypedMap = function(...args) {
-  return this.getMap(...args);
-};
-loroWasm.Loro.prototype.getTypedList = function(...args) {
-  return this.getList(...args);
-};
-loroWasm.LoroList.prototype.getTyped = function(loro, index) {
-  const value = this.get(index);
-  if (typeof value === "string" && isContainerId(value)) {
-    return loro.getContainerById(value);
-  } else {
-    return value;
-  }
-};
-loroWasm.LoroList.prototype.insertTyped = function(...args) {
-  return this.insert(...args);
-};
-loroWasm.LoroMap.prototype.getTyped = function(loro, key) {
-  const value = this.get(key);
-  if (typeof value === "string" && isContainerId(value)) {
-    return loro.getContainerById(value);
-  } else {
-    return value;
-  }
-};
-loroWasm.LoroMap.prototype.setTyped = function(...args) {
-  return this.set(...args);
-};
 const CONTAINER_TYPES = ["Map", "Text", "List", "Tree"];
@@ -35,0 +7,0 @@ function isContainerId(s) {

package.json

 {
   "name": "loro-crdt",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Loro CRDTs is a high-performance CRDT framework that makes your app state synchronized, collaborative and maintainable effortlessly.",
@@ -20,3 +20,3 @@ "keywords": [
   "dependencies": {
-    "loro-wasm": "0.13.1"
+    "loro-wasm": "0.14.0"
   },
@@ -41,5 +41,5 @@ "devDependencies": {
     "watch": "rollup -c -w",
-    "test": "vitest run --typecheck",
+    "test": "vitest run && npx tsc --noEmit",
     "prepublish": "pnpm run build"
   }
 }

src/index.ts

@@ -11,3 +11,2 @@ export * from "loro-wasm";
   LoroTree,
-  LoroTreeNode,
   OpId,
@@ -18,31 +17,2 @@ TreeID,
 
-Loro.prototype.getTypedMap = function (...args) {
-  return this.getMap(...args);
-};
-Loro.prototype.getTypedList = function (...args) {
-  return this.getList(...args);
-};
-LoroList.prototype.getTyped = function (loro, index) {
-  const value = this.get(index);
-  if (typeof value === "string" && isContainerId(value)) {
-    return loro.getContainerById(value);
-  } else {
-    return value;
-  }
-};
-LoroList.prototype.insertTyped = function (...args) {
-  return this.insert(...args);
-};
-LoroMap.prototype.getTyped = function (loro, key) {
-  const value = this.get(key);
-  if (typeof value === "string" && isContainerId(value)) {
-    return loro.getContainerById(value);
-  } else {
-    return value;
-  }
-};
-LoroMap.prototype.setTyped = function (...args) {
-  return this.set(...args);
-};
-
 export type Frontiers = OpId[];
@@ -61,3 +31,3 @@
  *
- * @prop local - Indicates whether the event is local.
+ * @prop by - How the event is triggered.
  * @prop origin - (Optional) Provides information about the origin of the event.
@@ -69,7 +39,10 @@ * @prop diff - Contains the differential information related to the event.
 export interface LoroEventBatch {
-  local: boolean;
   /**
-   * If true, this event was triggered by a checkout.
+   * How the event is triggered.
+   *
+   * - `local`: The event is triggered by a local transaction.
+   * - `import`: The event is triggered by an import operation.
+   * - `checkout`: The event is triggered by a checkout operation.
    */
-  fromCheckout: boolean;
+  by: "local" | "import" | "checkout";
   origin?: string;
@@ -203,27 +176,129 @@ /**
 
-  interface Loro<T extends Record<string, any> = Record<string, any>> {
-    getTypedMap<Key extends keyof T & string>(
+  interface Loro<
+    T extends Record<string, Container> = Record<string, Container>,
+  > {
+    /**
+     * Get a LoroMap by container id
+     *
+     * The object returned is a new js object each time because it need to cross
+     * the WASM boundary.
+     *
+     * @example
+     * ```ts
+     * import { Loro } from "loro-crdt";
+     *
+     * const doc = new Loro();
+     * const map = doc.getMap("map");
+     * ```
+     */
+    getMap<Key extends keyof T>(
       name: Key,
-    ): T[Key] extends LoroMap ? T[Key] : never;
-    getTypedList<Key extends keyof T & string>(
+    ): T[Key] extends LoroMap ? T[Key] : LoroMap;
+    /**
+     * Get a LoroList by container id
+     *
+     * The object returned is a new js object each time because it need to cross
+     * the WASM boundary.
+     *
+     * @example
+     * ```ts
+     * import { Loro } from "loro-crdt";
+     *
+     * const doc = new Loro();
+     * const list = doc.getList("list");
+     * ```
+     */
+    getList<Key extends keyof T>(
       name: Key,
-    ): T[Key] extends LoroList ? T[Key] : never;
-    getMap(key: string | ContainerID): LoroMap<T[string]>;
-    getList(key: string | ContainerID): LoroList<T[string]>;
-    getTree(key: string | ContainerID): LoroTree<T[string]>;
+    ): T[Key] extends LoroList ? T[Key] : LoroList;
+    /**
+     * Get a LoroTree by container id
+     *
+     *  The object returned is a new js object each time because it need to cross
+     *  the WASM boundary.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const tree = doc.getTree("tree");
+     *  ```
+     */
+    getTree<Key extends keyof T>(
+      name: Key,
+    ): T[Key] extends LoroTree ? T[Key] : LoroTree;
     getText(key: string | ContainerID): LoroText;
   }
 
-  interface LoroList<
-    T extends any[] = any[],
-  > {
+  interface LoroList<T = unknown> {
     new (): LoroList<T>;
+    /**
+     *  Get elements of the list. If the value is a child container, the corresponding
+     *  `Container` will be returned.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const list = doc.getList("list");
+     *  list.insert(0, 100);
+     *  list.insert(1, "foo");
+     *  list.insert(2, true);
+     *  list.insertContainer(3, new LoroText());
+     *  console.log(list.value);  // [100, "foo", true, LoroText];
+     *  ```
+     */
+    toArray(): T[];
+    /**
+     * Insert a container at the index.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const list = doc.getList("list");
+     *  list.insert(0, 100);
+     *  const text = list.insertContainer(1, new LoroText());
+     *  text.insert(0, "Hello");
+     *  console.log(list.getDeepValue());  // [100, "Hello"];
+     *  ```
+     */
     insertContainer<C extends Container>(
       pos: number,
       child: C,
-    ): C;
-    get(index: number): undefined | Value | Container;
-    getTyped<Key extends keyof T & number>(loro: Loro, index: Key): T[Key];
-    insertTyped<Key extends keyof T & number>(pos: Key, value: T[Key]): void;
-    insert(pos: number, value: Value): void;
+    ): T extends C ? T : C;
+    /**
+     * Get the value at the index. If the value is a container, the corresponding handler will be returned.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const list = doc.getList("list");
+     *  list.insert(0, 100);
+     *  console.log(list.get(0));  // 100
+     *  console.log(list.get(1));  // undefined
+     *  ```
+     */
+    get(index: number): T;
+    /**
+     *  Insert a value at index.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const list = doc.getList("list");
+     *  list.insert(0, 100);
+     *  list.insert(1, "foo");
+     *  list.insert(2, true);
+     *  console.log(list.value);  // [100, "foo", true];
+     *  ```
+     */
+    insert(pos: number, value: Exclude<T, Container>): void;
     delete(pos: number, len: number): void;
@@ -235,17 +310,74 @@ subscribe(txn: Loro, listener: Listener): number;
   interface LoroMap<
-    T extends Record<string, any> = Record<string, any>,
+    T extends Record<string, unknown> = Record<string, unknown>,
   > {
     new (): LoroMap<T>;
-    getOrCreateContainer<C extends Container>(
-      key: string,
+    /**
+     *  Get the value of the key. If the value is a child container, the corresponding
+     *  `Container` will be returned.
+     *
+     *  The object returned is a new js object each time because it need to cross
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const map = doc.getMap("map");
+     *  map.set("foo", "bar");
+     *  const bar = map.get("foo");
+     *  ```
+     */
+    getOrCreateContainer<C extends Container>(key: string, child: C): C;
+    /**
+     * Set the key with a container.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const map = doc.getMap("map");
+     *  map.set("foo", "bar");
+     *  const text = map.setContainer("text", new LoroText());
+     *  const list = map.setContainer("list", new LoroText());
+     *  ```
+     */
+    setContainer<C extends Container, Key extends keyof T>(
+      key: Key,
       child: C,
-    ): C;
-    setContainer<C extends Container>(
-      key: string,
-      child: C,
-    ): C;
-    get(key: string): undefined | Value | Container;
-    getTyped<Key extends keyof T & string>(txn: Loro, key: Key): T[Key];
-    set(key: string, value: Value): void;
-    setTyped<Key extends keyof T & string>(key: Key, value: T[Key]): void;
+    ): NonNullableType<T[Key]> extends C ? NonNullableType<T[Key]> : C;
+    /**
+     *  Get the value of the key. If the value is a child container, the corresponding
+     *  `Container` will be returned.
+     *
+     *  The object/value returned is a new js object/value each time because it need to cross
+     *  the WASM boundary.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const map = doc.getMap("map");
+     *  map.set("foo", "bar");
+     *  const bar = map.get("foo");
+     *  ```
+     */
+    get<Key extends keyof T>(key: Key): T[Key];
+    /**
+     * Set the key with the value.
+     *
+     *  If the value of the key is exist, the old value will be updated.
+     *
+     *  @example
+     *  ```ts
+     *  import { Loro } from "loro-crdt";
+     *
+     *  const doc = new Loro();
+     *  const map = doc.getMap("map");
+     *  map.set("foo", "bar");
+     *  map.set("foo", "baz");
+     *  ```
+     */
+    set<Key extends keyof T>(key: Key, value: Exclude<T[Key], Container>): void;
     delete(key: string): void;
@@ -263,3 +395,3 @@ subscribe(txn: Loro, listener: Listener): number;
   interface LoroTree<
-    T extends Record<string, any> = Record<string, any>,
+    T extends Record<string, unknown> = Record<string, unknown>,
   > {
@@ -276,4 +408,7 @@ new (): LoroTree<T>;
   interface LoroTreeNode<
-    T extends Record<string, any> = Record<string, any>,
+    T extends Record<string, unknown> = Record<string, unknown>,
   > {
+    /**
+     * Get the associated metadata map container of a tree node.
+     */
     readonly data: LoroMap<T>;
@@ -283,5 +418,7 @@ createNode(): LoroTreeNode<T>;
     moveTo(parent: LoroTreeNode<T>): void;
-    parent(): LoroTreeNode | undefined;
+    parent(): LoroTreeNode<T> | undefined;
     children(): Array<LoroTreeNode<T>>;
   }
 }
+
+type NonNullableType<T> = Exclude<T, null | undefined>;

tsconfig.json

@@ -53,5 +53,5 @@ {
     // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
-    "outDir": "./dist", /* Specify an output folder for all emitted files. */
+    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
     // "removeComments": true,                           /* Disable emitting comments. */
-    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
+    "noEmit": true /* Disable emitting files from a compilation. */,
     // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
@@ -58,0 +58,0 @@ // "importsNotUsedAsValues": "remove",               /* Specify emit/checking behavior for imports that are only used for types. */

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

191489

increased by65.42%

Number of package files

23

increased by76.92%

Lines of code

2598

increased by278.17%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedloro-wasm@0.14.0(transitive)

• - Removedloro-wasm@0.13.1(transitive)

• Updatedloro-wasm@0.14.0