@valbuild/core 0.12.0 → 0.13.0

package/src/patch/json.ts

@@ -0,0 +1,304 @@
+import { result, array, pipe } from "../fp/";
+import { JSONValue, Ops, PatchError, ReadonlyJSONValue } from "./ops";
+import {
+  deepClone,
+  deepEqual,
+  isNotRoot,
+  parseAndValidateArrayIndex,
+} from "./util";
+
+type JSONOpsResult<T> = result.Result<T, PatchError>;
+
+function parseAndValidateArrayInsertIndex(
+  key: string,
+  nodes: ReadonlyJSONValue[]
+): JSONOpsResult<number> {
+  if (key === "-") {
+    return result.ok(nodes.length);
+  }
+
+  return pipe(
+    parseAndValidateArrayIndex(key),
+    result.filterOrElse(
+      (index: number): boolean => index <= nodes.length,
+      () => new PatchError("Array index out of bounds")
+    )
+  );
+}
+
+function parseAndValidateArrayInboundsIndex(
+  key: string,
+  nodes: ReadonlyJSONValue[]
+): JSONOpsResult<number> {
+  return pipe(
+    parseAndValidateArrayIndex(key),
+    result.filterOrElse(
+      (index: number): boolean => index < nodes.length,
+      () => new PatchError("Array index out of bounds")
+    )
+  );
+}
+
+function replaceInNode(
+  node: JSONValue,
+  key: string,
+  value: JSONValue
+): JSONOpsResult<JSONValue> {
+  if (Array.isArray(node)) {
+    return pipe(
+      parseAndValidateArrayInboundsIndex(key, node),
+      result.map((index: number) => {
+        const replaced = node[index];
+        node[index] = value;
+        return replaced;
+      })
+    );
+  } else if (typeof node === "object" && node !== null) {
+    // Prototype pollution protection
+    if (Object.prototype.hasOwnProperty.call(node, key)) {
+      const replaced = node[key];
+      node[key] = value;
+      return result.ok(replaced);
+    } else {
+      return result.err(
+        new PatchError("Cannot replace object element which does not exist")
+      );
+    }
+  }
+
+  return result.err(new PatchError("Cannot replace in non-object/array"));
+}
+
+function replaceAtPath(
+  document: JSONValue,
+  path: string[],
+  value: JSONValue
+): JSONOpsResult<[document: JSONValue, replaced: JSONValue]> {
+  if (isNotRoot(path)) {
+    return pipe(
+      getPointerFromPath(document, path),
+      result.flatMap(([node, key]: Pointer) => replaceInNode(node, key, value)),
+      result.map((replaced: JSONValue) => [document, replaced])
+    );
+  } else {
+    return result.ok([value, document]);
+  }
+}
+
+function getFromNode(
+  node: JSONValue,
+  key: string
+): JSONOpsResult<JSONValue | undefined> {
+  if (Array.isArray(node)) {
+    return pipe(
+      parseAndValidateArrayIndex(key),
+      result.flatMap((index: number) => {
+        if (index >= node.length) {
+          return result.err(new PatchError("Array index out of bounds"));
+        } else {
+          return result.ok(node[index]);
+        }
+      })
+    );
+  } else if (typeof node === "object" && node !== null) {
+    // Prototype pollution protection
+    if (Object.prototype.hasOwnProperty.call(node, key)) {
+      return result.ok(node[key]);
+    } else {
+      return result.ok(undefined);
+    }
+  }
+
+  return result.err(new PatchError("Cannot access non-object/array"));
+}
+
+type Pointer = [node: JSONValue, key: string];
+function getPointerFromPath(
+  node: JSONValue,
+  path: array.NonEmptyArray<string>
+): JSONOpsResult<Pointer> {
+  let targetNode: JSONValue = node;
+  let key: string = path[0];
+  for (let i = 0; i < path.length - 1; ++i, key = path[i]) {
+    const childNode = getFromNode(targetNode, key);
+    if (result.isErr(childNode)) {
+      return childNode;
+    }
+    if (childNode.value === undefined) {
+      return result.err(
+        new PatchError("Path refers to non-existing object/array")
+      );
+    }
+    targetNode = childNode.value;
+  }
+
+  return result.ok([targetNode, key]);
+}
+
+function getAtPath(node: JSONValue, path: string[]): JSONOpsResult<JSONValue> {
+  return pipe(
+    path,
+    result.flatMapReduce(
+      (node: JSONValue, key: string) =>
+        pipe(
+          getFromNode(node, key),
+          result.filterOrElse(
+            (childNode: JSONValue | undefined): childNode is JSONValue =>
+              childNode !== undefined,
+            () => new PatchError("Path refers to non-existing object/array")
+          )
+        ),
+      node
+    )
+  );
+}
+
+function removeFromNode(
+  node: JSONValue,
+  key: string
+): JSONOpsResult<JSONValue> {
+  if (Array.isArray(node)) {
+    return pipe(
+      parseAndValidateArrayInboundsIndex(key, node),
+      result.map((index: number) => {
+        const [removed] = node.splice(index, 1);
+        return removed;
+      })
+    );
+  } else if (typeof node === "object" && node !== null) {
+    // Prototype pollution protection
+    if (Object.prototype.hasOwnProperty.call(node, key)) {
+      const removed = node[key];
+      delete node[key];
+      return result.ok(removed);
+    }
+  }
+
+  return result.err(new PatchError("Cannot remove from non-object/array"));
+}
+
+function removeAtPath(
+  document: JSONValue,
+  path: array.NonEmptyArray<string>
+): JSONOpsResult<JSONValue> {
+  return pipe(
+    getPointerFromPath(document, path),
+    result.flatMap(([node, key]: Pointer) => removeFromNode(node, key))
+  );
+}
+
+function addToNode(
+  node: JSONValue,
+  key: string,
+  value: JSONValue
+): JSONOpsResult<JSONValue | undefined> {
+  if (Array.isArray(node)) {
+    return pipe(
+      parseAndValidateArrayInsertIndex(key, node),
+      result.map((index: number) => {
+        node.splice(index, 0, value);
+        return undefined;
+      })
+    );
+  } else if (typeof node === "object" && node !== null) {
+    let replaced: JSONValue | undefined;
+    // Prototype pollution protection
+    if (Object.prototype.hasOwnProperty.call(node, key)) {
+      replaced = node[key];
+    }
+    node[key] = value;
+    return result.ok(replaced);
+  }
+
+  return result.err(new PatchError("Cannot add to non-object/array"));
+}
+
+function addAtPath(
+  document: JSONValue,
+  path: string[],
+  value: JSONValue
+): JSONOpsResult<[document: JSONValue, replaced?: JSONValue]> {
+  if (isNotRoot(path)) {
+    return pipe(
+      getPointerFromPath(document, path),
+      result.flatMap(([node, key]: Pointer) => addToNode(node, key, value)),
+      result.map((replaced: JSONValue | undefined) => [document, replaced])
+    );
+  } else {
+    return result.ok([value, document]);
+  }
+}
+
+function pickDocument<
+  T extends readonly [document: ReadonlyJSONValue, ...result: unknown[]]
+>([document]: T): T[0] {
+  return document;
+}
+
+export class JSONOps implements Ops<JSONValue, never> {
+  get(
+    document: JSONValue,
+    path: string[]
+  ): result.Result<JSONValue, PatchError> {
+    return getAtPath(document, path);
+  }
+  add(
+    document: JSONValue,
+    path: string[],
+    value: JSONValue
+  ): result.Result<JSONValue, PatchError> {
+    return pipe(addAtPath(document, path, value), result.map(pickDocument));
+  }
+  remove(
+    document: JSONValue,
+    path: array.NonEmptyArray<string>
+  ): result.Result<JSONValue, PatchError> {
+    return pipe(
+      removeAtPath(document, path),
+      result.map(() => document)
+    );
+  }
+  replace(
+    document: JSONValue,
+    path: string[],
+    value: JSONValue
+  ): result.Result<JSONValue, PatchError> {
+    return pipe(replaceAtPath(document, path, value), result.map(pickDocument));
+  }
+  move(
+    document: JSONValue,
+    from: array.NonEmptyArray<string>,
+    path: string[]
+  ): result.Result<JSONValue, PatchError> {
+    return pipe(
+      removeAtPath(document, from),
+      result.flatMap((removed: JSONValue) =>
+        addAtPath(document, path, removed)
+      ),
+      result.map(pickDocument)
+    );
+  }
+  copy(
+    document: JSONValue,
+    from: string[],
+    path: string[]
+  ): result.Result<JSONValue, PatchError> {
+    return pipe(
+      getAtPath(document, from),
+      result.flatMap((value: JSONValue) =>
+        addAtPath(document, path, deepClone(value))
+      ),
+      result.map(pickDocument)
+    );
+  }
+  test(
+    document: JSONValue,
+    path: string[],
+    value: JSONValue
+  ): result.Result<boolean, PatchError> {
+    return pipe(
+      getAtPath(document, path),
+      result.map((documentValue: JSONValue) => deepEqual(value, documentValue))
+    );
+  }
+}

package/src/patch/operation.ts

@@ -0,0 +1,74 @@
+import { array } from "../fp";
+import type { JSONValue } from "./ops";
+
+/**
+ * Raw JSON patch operation.
+ */
+export type OperationJSON =
+  | {
+      op: "add";
+      path: string;
+      value: JSONValue;
+    }
+  | {
+      op: "remove";
+      path: string;
+    }
+  | {
+      op: "replace";
+      path: string;
+      value: JSONValue;
+    }
+  | {
+      op: "move";
+      from: string;
+      path: string;
+    }
+  | {
+      op: "copy";
+      from: string;
+      path: string;
+    }
+  | {
+      op: "test";
+      path: string;
+      value: JSONValue;
+    };
+
+/**
+ * Parsed form of JSON patch operation.
+ */
+export type Operation =
+  | {
+      op: "add";
+      path: string[];
+      value: JSONValue;
+    }
+  | {
+      op: "remove";
+      path: array.NonEmptyArray<string>;
+    }
+  | {
+      op: "replace";
+      path: string[];
+      value: JSONValue;
+    }
+  | {
+      op: "move";
+      /**
+       * Must be non-root and not a proper prefix of "path".
+       */
+      // TODO: Replace with common prefix field
+      from: array.NonEmptyArray<string>;
+      path: string[];
+    }
+  | {
+      op: "copy";
+      from: string[];
+      path: string[];
+    }
+  | {
+      op: "test";
+      path: string[];
+      value: JSONValue;
+    };

package/src/patch/ops.ts

@@ -0,0 +1,83 @@
+import { result, array } from "../fp";
+
+export class PatchError {
+  constructor(public message: string) {}
+}
+
+export type ReadonlyJSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly ReadonlyJSONValue[]
+  | {
+      readonly [key: string]: ReadonlyJSONValue;
+    };
+
+export type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONValue[]
+  | {
+      [key: string]: JSONValue;
+    };
+
+type ToMutableJSONArray<T extends readonly ReadonlyJSONValue[]> = {
+  [P in keyof T]: ToMutable<T[P]>;
+};
+export type ToMutable<T extends ReadonlyJSONValue> = JSONValue extends T
+  ? JSONValue
+  : T extends readonly ReadonlyJSONValue[]
+  ? ToMutableJSONArray<T>
+  : T extends { readonly [key: string]: ReadonlyJSONValue }
+  ? { -readonly [P in keyof T]: ToMutable<T[P]> }
+  : T;
+
+type ToReadonlyJSONArray<T extends readonly ReadonlyJSONValue[]> = {
+  readonly [P in keyof T]: ToReadonly<T[P]>;
+};
+export type ToReadonly<T extends ReadonlyJSONValue> = JSONValue extends T
+  ? ReadonlyJSONValue
+  : T extends readonly ReadonlyJSONValue[]
+  ? ToReadonlyJSONArray<T>
+  : T extends { readonly [key: string]: ReadonlyJSONValue }
+  ? { readonly [P in keyof T]: ToReadonly<T[P]> }
+  : T;
+
+/**
+ * NOTE: MAY mutate the input document.
+ */
+export interface Ops<T, E> {
+  add(
+    document: T,
+    path: string[],
+    value: JSONValue
+  ): result.Result<T, E | PatchError>;
+  remove(
+    document: T,
+    path: array.NonEmptyArray<string>
+  ): result.Result<T, E | PatchError>;
+  replace(
+    document: T,
+    path: string[],
+    value: JSONValue
+  ): result.Result<T, E | PatchError>;
+  move(
+    document: T,
+    from: array.NonEmptyArray<string>,
+    path: string[]
+  ): result.Result<T, E | PatchError>;
+  copy(
+    document: T,
+    from: string[],
+    path: string[]
+  ): result.Result<T, E | PatchError>;
+  test(
+    document: T,
+    path: string[],
+    value: JSONValue
+  ): result.Result<boolean, E | PatchError>;
+  get(document: T, path: string[]): result.Result<JSONValue, E | PatchError>;
+}

package/src/patch/parse.test.ts

@@ -0,0 +1,202 @@
+import {
+  formatJSONPointer,
+  parseJSONPointer,
+  parseOperation,
+  StaticPatchIssue,
+} from "./parse";
+import * as result from "../fp/result";
+import { Operation, OperationJSON } from "./operation";
+import { array } from "../fp";
+
+describe("parseOperation", () => {
+  test.each<{
+    name: string;
+    value: OperationJSON;
+    expected: Operation;
+  }>([
+    {
+      name: "basic add operation",
+      value: {
+        op: "add",
+        path: "/",
+        value: null,
+      },
+      expected: {
+        op: "add",
+        path: [],
+        value: null,
+      },
+    },
+    {
+      name: "basic remove operation",
+      value: {
+        op: "remove",
+        path: "/foo",
+      },
+      expected: {
+        op: "remove",
+        path: ["foo"],
+      },
+    },
+    {
+      name: "basic replace operation",
+      value: {
+        op: "replace",
+        path: "/",
+        value: null,
+      },
+      expected: {
+        op: "replace",
+        path: [],
+        value: null,
+      },
+    },
+    {
+      name: "basic move operation",
+      value: {
+        op: "move",
+        from: "/foo",
+        path: "/bar",
+      },
+      expected: {
+        op: "move",
+        from: ["foo"],
+        path: ["bar"],
+      },
+    },
+    {
+      name: "basic copy operation",
+      value: {
+        op: "copy",
+        from: "/foo",
+        path: "/bar",
+      },
+      expected: {
+        op: "copy",
+        from: ["foo"],
+        path: ["bar"],
+      },
+    },
+    {
+      name: "basic test operation",
+      value: {
+        op: "test",
+        path: "/",
+        value: null,
+      },
+      expected: {
+        op: "test",
+        path: [],
+        value: null,
+      },
+    },
+  ])("$name is valid", ({ value, expected }) => {
+    const res = parseOperation(value);
+    expect(res).toEqual(result.ok(expected));
+  });
+
+  test.each<{
+    name: string;
+    value: OperationJSON;
+    errors: array.NonEmptyArray<string[]>;
+  }>([
+    {
+      name: "add operation with empty path",
+      value: {
+        op: "add",
+        path: "",
+        value: null,
+      },
+      errors: [["path"]],
+    },
+    {
+      name: "remove root",
+      value: {
+        op: "remove",
+        path: "/",
+      },
+      errors: [["path"]],
+    },
+    {
+      name: "move from root",
+      value: {
+        op: "move",
+        from: "/",
+        path: "/",
+      },
+      errors: [["from"]],
+    },
+    {
+      name: "move from prefix of path",
+      value: {
+        op: "move",
+        from: "/foo",
+        path: "/foo/bar",
+      },
+      errors: [["from"]],
+    },
+  ])("$name is invalid", ({ value, errors }) => {
+    expect(parseOperation(value)).toEqual(
+      result.err(
+        expect.arrayContaining<array.NonEmptyArray<StaticPatchIssue>>(
+          errors.map((path) =>
+            expect.objectContaining<StaticPatchIssue>({
+              path,
+              message: expect.anything(),
+            })
+          )
+        )
+      )
+    );
+  });
+});
+
+const JSONPointerTestCases: { str: string; arr: string[] }[] = [
+  {
+    str: "/",
+    arr: [],
+  },
+  {
+    str: "/foo",
+    arr: ["foo"],
+  },
+  {
+    str: "/foo/",
+    arr: ["foo", ""],
+  },
+  {
+    str: "/~1",
+    arr: ["/"],
+  },
+  {
+    str: "/~1/~1",
+    arr: ["/", "/"],
+  },
+  {
+    str: "/~0",
+    arr: ["~"],
+  },
+  {
+    str: "/~0/~0",
+    arr: ["~", "~"],
+  },
+];
+
+describe("parseJSONPointer", () => {
+  test.each(JSONPointerTestCases)("valid: $str", ({ str, arr }) => {
+    expect(parseJSONPointer(str)).toEqual(result.ok(arr));
+  });
+
+  test.each(["", "foo", "foo/bar", "/~2", "/~"])(
+    "invalid: %s",
+    (path: string) => {
+      expect(parseJSONPointer(path)).toEqual(result.err(expect.any(String)));
+    }
+  );
+});
+
+describe("formatJSONPointer", () => {
+  test.each(JSONPointerTestCases)("$str", ({ str, arr }) => {
+    expect(formatJSONPointer(arr)).toEqual(str);
+  });
+});