@mml-io/networked-dom-document 0.15.0 → 0.16.0

package/build/rfc6902/diff.d.ts

@@ -0,0 +1,167 @@
+import { Pointer } from "./pointer";
+/**
+All diff* functions should return a list of operations, often empty.
+
+Each operation should be an object with two to four fields:
+* `op`: the name of the operation; one of "add", "remove", "replace", "move",
+  "copy", or "test".
+* `path`: a JSON pointer string
+* `from`: a JSON pointer string
+* `value`: a JSON value
+
+The different operations have different arguments.
+* "add": [`path`, `value`]
+* "remove": [`path`]
+* "replace": [`path`, `value`]
+* "move": [`from`, `path`]
+* "copy": [`from`, `path`]
+* "test": [`path`, `value`]
+
+Currently this only really differentiates between Arrays, Objects, and
+Everything Else, which is pretty much just what JSON substantially
+differentiates between.
+*/
+export interface AddOperation {
+    op: "add";
+    path: string;
+    value: any;
+}
+export interface RemoveOperation {
+    op: "remove";
+    path: string;
+}
+export interface ReplaceOperation {
+    op: "replace";
+    path: string;
+    value: any;
+}
+export interface MoveOperation {
+    op: "move";
+    from: string;
+    path: string;
+}
+export interface CopyOperation {
+    op: "copy";
+    from: string;
+    path: string;
+}
+export interface TestOperation {
+    op: "test";
+    path: string;
+    value: any;
+}
+export type Operation = AddOperation | RemoveOperation | ReplaceOperation | MoveOperation | CopyOperation | TestOperation;
+export declare function isDestructive({ op }: Operation): boolean;
+export type Diff = (input: any, output: any, ptr: Pointer) => Operation[];
+/**
+VoidableDiff exists to allow the user to provide a partial diff(...) function,
+falling back to the built-in diffAny(...) function if the user-provided function
+returns void.
+*/
+export type VoidableDiff = (input: any, output: any, ptr: Pointer) => Operation[] | void;
+/**
+ Produce an 'application/json-patch+json'-type list of tests, to verify that
+ existing values in an object are identical to the those captured at some
+ checkpoint (whenever this function is called).
+
+ This does not alter `input` or `output` unless they have a property getter with
+ side-effects (which is not a good idea anyway).
+
+ Returns list of test operations.
+ */
+export declare function createTests(input: any, patch: Operation[]): TestOperation[];
+/**
+ Produce a 'application/json-patch+json'-type patch to get from one object to
+ another.
+
+ This does not alter `input` or `output` unless they have a property getter with
+ side-effects (which is not a good idea anyway).
+
+ `diff` is called on each pair of comparable non-primitive nodes in the
+ `input`/`output` object trees, producing nested patches. Return `undefined`
+ to fall back to default behaviour.
+
+ Returns list of operations to perform on `input` to produce `output`.
+ */
+export declare function createPatch(input: any, output: any, diff?: VoidableDiff): Operation[];
+/**
+List the keys in `minuend` that are not in `subtrahend`.
+
+A key is only considered if it is both 1) an own-property (o.hasOwnProperty(k))
+of the object, and 2) has a value that is not undefined. This is to match JSON
+semantics, where JSON object serialization drops keys with undefined values.
+
+@param minuend Object of interest
+@param subtrahend Object of comparison
+@returns Array of keys that are in `minuend` but not in `subtrahend`.
+*/
+export declare function subtract(minuend: {
+    [index: string]: any;
+}, subtrahend: {
+    [index: string]: any;
+}): string[];
+/**
+List the keys that shared by all `objects`.
+
+The semantics of what constitutes a "key" is described in {@link subtract}.
+
+@param objects Array of objects to compare
+@returns Array of keys that are in ("own-properties" of) every object in `objects`.
+*/
+export declare function intersection(objects: ArrayLike<{
+    [index: string]: any;
+}>): string[];
+/**
+Calculate the shortest sequence of operations to get from `input` to `output`,
+using a dynamic programming implementation of the Levenshtein distance algorithm.
+
+To get from the input ABC to the output AZ we could just delete all the input
+and say "insert A, insert Z" and be done with it. That's what we do if the
+input is empty. But we can be smarter.
+
+          output
+               A   Z
+               -   -
+          [0]  1   2
+input A |  1  [0]  1
+      B |  2  [1]  1
+      C |  3   2  [2]
+
+1) start at 0,0 (+0)
+2) keep A (+0)
+3) remove B (+1)
+4) replace C with Z (+1)
+
+If the `input` (source) is empty, they'll all be in the top row, resulting in an
+array of 'add' operations.
+If the `output` (target) is empty, everything will be in the left column,
+resulting in an array of 'remove' operations.
+
+@returns A list of add/remove/replace operations.
+*/
+export declare function diffArrays<T>(input: T[], output: T[], ptr: Pointer, diff?: Diff): Operation[];
+export declare function diffObjects(input: any, output: any, ptr: Pointer, diff?: Diff): Operation[];
+/**
+`diffAny()` returns an empty array if `input` and `output` are materially equal
+(i.e., would produce equivalent JSON); otherwise it produces an array of patches
+that would transform `input` into `output`.
+
+> Here, "equal" means that the value at the target location and the
+> value conveyed by "value" are of the same JSON type, and that they
+> are considered equal by the following rules for that type:
+> o  strings: are considered equal if they contain the same number of
+>    Unicode characters and their code points are byte-by-byte equal.
+> o  numbers: are considered equal if their values are numerically
+>    equal.
+> o  arrays: are considered equal if they contain the same number of
+>    values, and if each value can be considered equal to the value at
+>    the corresponding position in the other array, using this list of
+>    type-specific rules.
+> o  objects: are considered equal if they contain the same number of
+>    members, and if each member can be considered equal to a member in
+>    the other object, by comparing their keys (as strings) and their
+>    values (using this list of type-specific rules).
+> o  literals (false, true, and null): are considered equal if they are
+>    the same.
+*/
+export declare function diffAny(input: any, output: any, ptr: Pointer, diff?: Diff): Operation[];

package/build/rfc6902/index.d.ts

@@ -0,0 +1,4 @@
+export { Pointer } from "./pointer";
+export { applyPatch } from "./patch";
+export type { Operation, TestOperation } from "./diff";
+export { createPatch, createTests } from "./diff";

package/build/rfc6902/patch.d.ts

@@ -0,0 +1,102 @@
+import { AddOperation, CopyOperation, MoveOperation, Operation, RemoveOperation, ReplaceOperation, TestOperation } from "./diff";
+export declare class MissingError extends Error {
+    path: string;
+    constructor(path: string);
+}
+export declare class TestError extends Error {
+    actual: any;
+    expected: any;
+    constructor(actual: any, expected: any);
+}
+/**
+ Apply a 'application/json-patch+json'-type patch to an object.
+
+ `patch` *must* be an array of operations.
+
+ > Operation objects MUST have exactly one "op" member, whose value
+ > indicates the operation to perform.  Its value MUST be one of "add",
+ > "remove", "replace", "move", "copy", or "test"; other values are
+ > errors.
+
+ This method mutates the target object in-place.
+
+ @returns list of results, one for each operation: `null` indicated success,
+ otherwise, the result will be an instance of one of the Error classes:
+ MissingError, InvalidOperationError, or TestError.
+ */
+export declare function applyPatch(object: any, patch: Operation[]): (MissingError | TestError | InvalidOperationError | null)[];
+/**
+>  o  If the target location specifies an array index, a new value is
+>     inserted into the array at the specified index.
+>  o  If the target location specifies an object member that does not
+>     already exist, a new member is added to the object.
+>  o  If the target location specifies an object member that does exist,
+>     that member's value is replaced.
+*/
+export declare function add(object: any, operation: AddOperation): MissingError | null;
+/**
+> The "remove" operation removes the value at the target location.
+> The target location MUST exist for the operation to be successful.
+*/
+export declare function remove(object: any, operation: RemoveOperation): MissingError | null;
+/**
+> The "replace" operation replaces the value at the target location
+> with a new value.  The operation object MUST contain a "value" member
+> whose content specifies the replacement value.
+> The target location MUST exist for the operation to be successful.
+
+> This operation is functionally identical to a "remove" operation for
+> a value, followed immediately by an "add" operation at the same
+> location with the replacement value.
+
+Even more simply, it's like the add operation with an existence check.
+*/
+export declare function replace(object: any, operation: ReplaceOperation): MissingError | null;
+/**
+> The "move" operation removes the value at a specified location and
+> adds it to the target location.
+> The operation object MUST contain a "from" member, which is a string
+> containing a JSON Pointer value that references the location in the
+> target document to move the value from.
+> This operation is functionally identical to a "remove" operation on
+> the "from" location, followed immediately by an "add" operation at
+> the target location with the value that was just removed.
+
+> The "from" location MUST NOT be a proper prefix of the "path"
+> location; i.e., a location cannot be moved into one of its children.
+
+TODO: throw if the check described in the previous paragraph fails.
+*/
+export declare function move(object: any, operation: MoveOperation): MissingError | null;
+/**
+> The "copy" operation copies the value at a specified location to the
+> target location.
+> The operation object MUST contain a "from" member, which is a string
+> containing a JSON Pointer value that references the location in the
+> target document to copy the value from.
+> The "from" location MUST exist for the operation to be successful.
+
+> This operation is functionally identical to an "add" operation at the
+> target location using the value specified in the "from" member.
+
+Alternatively, it's like 'move' without the 'remove'.
+*/
+export declare function copy(object: any, operation: CopyOperation): MissingError | null;
+/**
+> The "test" operation tests that a value at the target location is
+> equal to a specified value.
+> The operation object MUST contain a "value" member that conveys the
+> value to be compared to the target location's value.
+> The target location MUST be equal to the "value" value for the
+> operation to be considered successful.
+*/
+export declare function test(object: any, operation: TestOperation): TestError | null;
+export declare class InvalidOperationError extends Error {
+    operation: Operation;
+    constructor(operation: Operation);
+}
+/**
+Switch on `operation.op`, applying the corresponding patch function for each
+case to `object`.
+*/
+export declare function apply(object: any, operation: Operation): MissingError | InvalidOperationError | TestError | null;

package/build/rfc6902/pointer.d.ts

@@ -0,0 +1,33 @@
+export interface PointerEvaluation {
+    parent: any;
+    key: string;
+    value: any;
+}
+/**
+JSON Pointer representation
+*/
+export declare class Pointer {
+    tokens: string[];
+    constructor(tokens?: string[]);
+    /**
+    `path` *must* be a properly escaped string.
+    */
+    static fromJSON(path: string): Pointer;
+    toString(): string;
+    /**
+    Returns an object with 'parent', 'key', and 'value' properties.
+    In the special case that this Pointer's path == "",
+    this object will be {parent: null, key: '', value: object}.
+    Otherwise, parent and key will have the property such that parent[key] == value.
+    */
+    evaluate(object: any): PointerEvaluation;
+    get(object: any): any;
+    set(object: any, value: any): void;
+    push(token: string): void;
+    /**
+    `token` should be a String. It'll be coerced to one anyway.
+  
+    immutable (shallowly)
+    */
+    add(token: string): Pointer;
+}

package/build/rfc6902/util.d.ts

@@ -0,0 +1,10 @@
+export declare const hasOwnProperty: (v: PropertyKey) => boolean;
+export declare function objectType(object: any): "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array";
+/**
+Recursively copy a value.
+
+@param source - should be a JavaScript primitive, Array, Date, or (plain old) Object.
+@returns copy of source where every Array and Object have been recursively
+         reconstructed from their constituent elements
+*/
+export declare function clone<T>(source: T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mml-io/networked-dom-document",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,9 +19,8 @@
     "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest"
   },
   "dependencies": {
-    "@mml-io/networked-dom-protocol": "^0.15.0",
-    "@mml-io/observable-dom-common": "^0.15.0",
-    "rfc6902": "5.1.1"
+    "@mml-io/networked-dom-protocol": "^0.16.0",
+    "@mml-io/observable-dom-common": "^0.16.0"
   },
-  "gitHead": "09c8250150fbb464d6b94f27976078366885b858"
+  "gitHead": "b63e712f9e21e9f165ba3845e4c8b5f66af064b1"
 }