@hyperjump/json-pointer 1.0.1 → 1.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Jason Desrosiers
+Copyright (c) 2018 Hyperjump Software, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,24 +1,22 @@
-JSON Pointer
-============
+# JSON Pointer
 
 This is an implementation of RFC-6901 JSON Pointer. JSON Pointer is designed for
 referring to data values within a JSON document. It's designed to be URL
 friendly so it can be used as a URL fragment that points to a specific part of
 the JSON document.
 
-Installation
-------------
+## Installation
+
 Includes support for node.js (ES Modules, TypeScript) and browsers.
 
 ```bash
 npm install @hyperjump/json-pointer
 ```
 
-Usage
------
+## Usage
 
 ```javascript
-const JsonPointer = require("@hyperjump/json-pointer");
+import * as JsonPointer from "@hyperjump/json-pointer";
 
 const value = {
   "foo": {
@@ -27,7 +25,7 @@ const value = {
 };
 
 // Construct pointers
-const fooPointer = JsonPointer.append(JsonPointer.nil, "foo"); // "/foo"
+const fooPointer = JsonPointer.append("foo", JsonPointer.nil); // "/foo"
 const fooBarPointer = JsonPointer.append(fooPointer, "bar"); // "/foo/bar"
 
 // Get a value from a pointer
@@ -55,8 +53,40 @@ const deleteFooBar = JsonPointer.remove(fooBarPointer);
 deleteFooBar(value); // { "foo": {} }
 ```
 
-Contributing
-------------
+## API
+
+* **nil**: ""
+
+    The empty pointer.
+* **pointerSegments**: (pointer: string) => Generator\<string>
+
+    An iterator for the segments of a JSON Pointer that handles escaping.
+* **append**: (segment: string, pointer: string) => string
+
+    Append a segment to a JSON Pointer.
+* **get**: (pointer: string, subject: any) => any
+
+    Use a JSON Pointer to get a value. This function can be curried.
+* **set**: (pointer: string, subject: any, value: any) => any
+
+    Immutably set a value using a JSON Pointer. Returns a new version of
+    `subject` with the value set. The original `subject` is not changed, but the
+    value isn't entirely cloned. Values that aren't changed will point to
+    the same value as the original. This function can be curried.
+* **assign**: (pointer: string, subject: any, value: any) => void
+
+    Mutate a value using a JSON Pointer. This function can be curried.
+* **unset**: (pointer: string, subject: any) => any
+
+    Immutably delete a value using a JSON Pointer. Returns a new version of
+    `subject` without the value. The original `subject` is not changed, but the
+    value isn't entirely cloned. Values that aren't changed will point to the
+    same value as the original. This function can be curried.
+* **remove**: (pointer: string, subject: any) => void
+
+    Delete a value using a JSON Pointer. This function can be curried.
+
+## Contributing
 
 ### Tests
 

package/lib/index.d.ts

@@ -1,52 +1,40 @@
-export const nil: "";
-export const append: (
-    (segment: string, pointer: string) => string
-  ) & (
-    (segment: string) => (pointer: string) => string
-  );
-export const get: (
-    (pointer: string, subject: Pointable) => unknown
-  ) & (
-    (pointer: string) => Getter
-  );
-export const set: (
-    <A extends Pointable>(pointer: string, subject: A, value: unknown) => A
-  ) & (
-    (pointer: string) => Setter
-  );
-export const assign: (
-    <A extends Pointable>(pointer: string, subject: A, value: unknown) => void
-  ) & (
-    (pointer: string) => Assigner
-  );
-export const unset: (
-    <A extends Pointable>(pointer: string, subject: A) => A
-  ) & (
-    (pointer: string) => Unsetter
-  );
-export const remove: (
-    (pointer: string, subject: Pointable) => void
-  ) & (
-    (pointer: string) => Remover
-  );
-
-export type Getter = (subject: Pointable) => unknown;
-export type Setter = (
-  <A extends Pointable>(subject: A, value: unknown) => A
-) & (
-  <A extends Pointable>(subject: A) => (value: unknown) => A
-);
-export type Assigner = (
-  <A extends Pointable>(subject: A, value: unknown) => void
-) & (
-  <A extends Pointable>(subject: A) => (value: unknown) => void
-);
-export type Unsetter = <A extends Pointable>(subject: A) => A;
-export type Remover = (subject: Pointable) => void;
-
 export type Json = string | number | boolean | null | JsonObject | Json[];
 export type JsonObject = {
   [property: string]: Json;
 };
 
-export type Pointable = JsonObject | Json[];
+export const nil: "";
+
+export const pointerSegments: (pointer: string) => Generator<string>;
+
+export const append: (segment: string, pointer: string) => string;
+
+export const get: {
+  (pointer: string, subject: Json): Json | undefined;
+  (pointer: string): Getter;
+};
+export type Getter = (subject: Json) => Json | undefined;
+
+export const set: {
+  (pointer: string, subject: Json, value: Json): Json;
+  (pointer: string): Setter;
+};
+export type Setter = (subject: Json, value: Json) => Json;
+
+export const assign: {
+  (pointer: string, subject: Json, value: Json): void;
+  (pointer: string): Assigner;
+};
+export type Assigner = (subject: Json, value: Json) => void;
+
+export const unset: {
+  (pointer: string, subject: Json): Json | undefined;
+  (pointer: string): Unsetter;
+};
+export type Unsetter = (subject: Json) => Json | undefined;
+
+export const remove: {
+  (pointer: string, subject: Json): void;
+  (pointer: string): Remover;
+};
+export type Remover = (subject: Json) => void;

package/lib/index.js

@@ -1,149 +1,310 @@
-import curry from "just-curry-it";
+/** @import * as API from "./index.d.ts" */
 
 
+/** @type API.nil */
 export const nil = "";
 
-const EXISTS = Symbol("EXISTS");
-
-const segmentGenerator = (pointer) => {
-  if (pointer.length > 0 && pointer[0] !== "/") {
+/** @type API.pointerSegments */
+export const pointerSegments = function* (pointer) {
+  if (pointer.length > 0 && !pointer.startsWith("/")) {
     throw Error("Invalid JSON Pointer");
   }
 
   let segmentStart = 1;
   let segmentEnd = 0;
 
-  return (mode) => {
-    if (mode === EXISTS) {
-      return segmentEnd < pointer.length;
-    }
-
-    if (segmentEnd >= pointer.length) {
-      return;
-    }
-
+  while (segmentEnd < pointer.length) {
     const position = pointer.indexOf("/", segmentStart);
     segmentEnd = position === -1 ? pointer.length : position;
-    const segment = unescape(pointer.slice(segmentStart, segmentEnd));
+    const segment = pointer.slice(segmentStart, segmentEnd);
     segmentStart = segmentEnd + 1;
 
-    return segment;
-  };
+    yield unescape(segment);
+  }
 };
 
+/**
+ * @overload
+ * @param {string} pointer
+ * @return {API.Getter}
+ *
+ * @overload
+ * @param {string} pointer
+ * @param {API.Json} subject
+ * @return {API.Json | undefined}
+ *
+ * @param {string} pointer
+ * @param {API.Json} [subject]
+ * @return {API.Json | undefined | API.Getter}
+ *
+ * @type API.get
+ */
 export const get = (pointer, subject = undefined) => {
-  const nextSegment = segmentGenerator(pointer);
-  const fn = (subject) => _get(nextSegment, subject, nil);
-  return subject === undefined ? fn : fn(subject);
+  if (subject === undefined) {
+    const segments = [...pointerSegments(pointer)];
+    return (subject) => _get(segments, subject);
+  } else {
+    return _get(pointerSegments(pointer), subject);
+  }
 };
 
-const _get = (nextSegment, subject, cursor) => {
-  if (!nextSegment(EXISTS)) {
-    return subject;
-  } else {
-    const segment = nextSegment();
-    return _get(nextSegment, applySegment(subject, segment, cursor), append(segment, cursor));
+/** @type (segments: Iterable<string>, subject: API.Json | undefined) => API.Json | undefined */
+const _get = (segments, subject) => {
+  /** @type string */
+  let cursor = nil;
+  for (const segment of segments) {
+    subject = applySegment(subject, segment, cursor);
+    cursor = append(segment, cursor);
   }
+
+  return subject;
 };
 
+/**
+ * @overload
+ * @param {string} pointer
+ * @return {API.Setter}
+ *
+ * @overload
+ * @param {string} pointer
+ * @param {API.Json} subject
+ * @param {API.Json} value
+ * @return {API.Json}
+ *
+ * @param {string} pointer
+ * @param {API.Json} [subject]
+ * @param {API.Json} [value]
+ * @return {API.Json | API.Setter}
+ *
+ * @type API.set
+ */
 export const set = (pointer, subject = undefined, value = undefined) => {
-  const nextSegment = segmentGenerator(pointer);
-  const fn = curry((subject, value) => _set(nextSegment, subject, value, nil));
-  return subject === undefined ? fn : fn(subject, value);
+  if (subject === undefined) {
+    return (subject, value) => _set(pointerSegments(pointer), subject, value);
+  } else {
+    return _set(pointerSegments(pointer), subject, /** @type API.Json */ (value));
+  }
 };
 
-const _set = (nextSegment, subject, value, cursor) => {
-  const segment = nextSegment();
-  if (segment === undefined) {
+/** @type (segments: Generator<string>, subject: API.Json | undefined, value: API.Json, cursor?: string) => API.Json */
+const _set = (segments, subject, value, cursor = nil) => {
+  const segment = segments.next();
+  if (segment.done) {
     return value;
-  } else if (nextSegment(EXISTS)) {
-    if (Array.isArray(subject)) {
-      const clonedSubject = [...subject];
-      clonedSubject[segment] = _set(nextSegment, applySegment(subject, segment, cursor), value, append(segment, cursor));
-      return clonedSubject;
-    } else {
-      return { ...subject, [segment]: _set(nextSegment, applySegment(subject, segment, cursor), value, append(segment, cursor)) };
-    }
-  } else if (Array.isArray(subject)) {
-    const clonedSubject = [...subject];
-    clonedSubject[computeSegment(subject, segment)] = value;
-    return clonedSubject;
+  }
+
+  if (Array.isArray(subject)) {
+    subject = [...subject];
   } else if (typeof subject === "object" && subject !== null) {
-    return { ...subject, [segment]: value };
+    subject = { ...subject };
   } else {
-    return applySegment(subject, segment, cursor);
+    applySegment(subject, segment.value, cursor);
   }
+  cursor = append(segment.value, cursor);
+
+  // currentSubject could also be an array, but this appeases the type system
+  const currentSubject = /** @type API.JsonObject */ (subject);
+  const computedSegment = computeSegment(subject, segment.value);
+  currentSubject[computedSegment] = _set(segments, currentSubject[computedSegment], value, cursor);
+  return currentSubject;
 };
 
+/**
+ * @overload
+ * @param {string} pointer
+ * @returns {API.Assigner}
+ *
+ * @overload
+ * @param {string} pointer
+ * @param {API.Json} subject
+ * @param {API.Json} value
+ * @returns {void}
+ *
+ * @param {string} pointer
+ * @param {API.Json} [subject]
+ * @param {API.Json} [value]
+ * @returns {void | API.Assigner}
+ *
+ * @type API.assign
+ */
 export const assign = (pointer, subject = undefined, value = undefined) => {
-  const nextSegment = segmentGenerator(pointer);
-  const fn = curry((subject, value) => _assign(nextSegment, subject, value, nil));
-  return subject === undefined ? fn : fn(subject, value);
+  if (subject === undefined) {
+    return (subject, value) => _assign(pointerSegments(pointer), subject, value);
+  } else {
+    return _assign(pointerSegments(pointer), subject, /** @type API.Json */ (value));
+  }
 };
 
-const _assign = (nextSegment, subject, value, cursor) => {
-  const segment = nextSegment();
-  if (segment === undefined) {
+/** @type (segments: Generator<string>, subject: API.Json, value: API.Json, cursor?: string) => void */
+const _assign = (segments, subject, value, cursor = nil) => {
+  /** @type string | undefined */
+  let lastSegment;
+
+  /** @type API.Json | undefined */
+  let currentSubject = subject;
+
+  /** @type API.Json | undefined */
+  let lastSubject;
+
+  for (let segment of segments) {
+    segment = computeSegment(currentSubject, segment);
+    lastSegment = segment;
+    lastSubject = currentSubject;
+    currentSubject = applySegment(currentSubject, segment, cursor);
+    cursor = append(segment, cursor);
+  }
+
+  if (lastSegment === undefined) {
     return;
-  } else if (!nextSegment(EXISTS) && !isScalar(subject)) {
-    subject[computeSegment(subject, segment)] = value;
-  } else {
-    _assign(nextSegment, applySegment(subject, segment, cursor), value, append(segment, cursor));
   }
+
+  // lastSubject could also be an array, but this appeases the type system
+  /** @type API.JsonObject */ (lastSubject)[lastSegment] = value;
 };
 
+/**
+ * @overload
+ * @param {string} pointer
+ * @returns {API.Unsetter}
+ *
+ * @overload
+ * @param {string} pointer
+ * @param {API.Json} subject
+ * @returns {API.Json | undefined}
+ *
+ * @param {string} pointer
+ * @param {API.Json} [subject]
+ * @returns {API.Json | undefined | API.Unsetter}
+ *
+ * @type API.unset
+ */
 export const unset = (pointer, subject = undefined) => {
-  const nextSegment = segmentGenerator(pointer);
-  const fn = (subject) => _unset(nextSegment, subject, nil);
-  return subject === undefined ? fn : fn(subject);
+  if (subject === undefined) {
+    return (subject) => _unset(pointerSegments(pointer), subject);
+  } else {
+    return _unset(pointerSegments(pointer), subject);
+  }
 };
 
-const _unset = (nextSegment, subject, cursor) => {
-  const segment = nextSegment();
-  if (segment === undefined) {
+/**
+ * @param {Generator<string>} segments
+ * @param {API.Json | undefined} [subject]
+ * @param {string} [cursor]
+ * @returns {API.JsonObject | API.Json[] | undefined}
+ */
+const _unset = (segments, subject, cursor = nil) => {
+  const segment = segments.next();
+  if (segment.done) {
     return;
-  } else if (nextSegment(EXISTS)) {
-    const value = applySegment(subject, segment, cursor);
-    return { ...subject, [segment]: _unset(nextSegment, value, append(segment, cursor)) };
-  } else if (Array.isArray(subject)) {
-    const clonedSubject = [...subject];
-    delete clonedSubject[computeSegment(subject, segment)];
-    return clonedSubject;
+  }
+
+  if (Array.isArray(subject)) {
+    subject = [...subject];
   } else if (typeof subject === "object" && subject !== null) {
-    // eslint-disable-next-line no-unused-vars
-    const { [segment]: _, ...result } = subject;
-    return result;
+    subject = { ...subject };
   } else {
-    return applySegment(subject, segment, cursor);
+    applySegment(subject, segment.value, cursor);
   }
+  cursor = append(segment.value, cursor);
+
+  // currentSubject could also be an array, but this appeases the type system
+  const currentSubject = /** @type API.JsonObject */ (subject);
+  const computedSegment = computeSegment(currentSubject, segment.value);
+  const unsetSubject = _unset(segments, currentSubject[computedSegment], cursor);
+  if (computedSegment in currentSubject) {
+    if (unsetSubject === undefined) {
+      delete currentSubject[computedSegment];
+    } else {
+      currentSubject[computedSegment] = unsetSubject;
+    }
+  }
+  return currentSubject;
 };
 
+/**
+ * @overload
+ * @param {string} pointer
+ * @returns {API.Remover}
+ *
+ * @overload
+ * @param {string} pointer
+ * @param {API.Json} subject
+ * @returns {void}
+ *
+ * @param {string} pointer
+ * @param {API.Json} [subject]
+ * @returns {void | API.Remover}
+ *
+ * @type API.remove
+ */
 export const remove = (pointer, subject = undefined) => {
-  const nextSegment = segmentGenerator(pointer);
-  const fn = (subject) => _remove(nextSegment, subject, nil);
-  return subject === undefined ? fn : fn(subject);
+  if (subject === undefined) {
+    return (subject) => _remove(pointerSegments(pointer), subject);
+  } else {
+    return _remove(pointerSegments(pointer), subject);
+  }
 };
 
-const _remove = (nextSegment, subject, cursor) => {
-  const segment = nextSegment();
-  if (segment === undefined) {
+/** @type (segments: Generator<string>, subject: API.Json, cursor?: string) => void */
+const _remove = (segments, subject, cursor = nil) => {
+  /** @type string | undefined */
+  let lastSegment;
+
+  /** @type API.Json | undefined */
+  let currentSubject = subject;
+
+  /** @type API.Json | undefined */
+  let lastSubject;
+
+  for (let segment of segments) {
+    segment = computeSegment(currentSubject, segment);
+    lastSegment = segment;
+    lastSubject = currentSubject;
+    currentSubject = applySegment(currentSubject, segment, cursor);
+    cursor = append(segment, cursor);
+  }
+
+  if (lastSegment === undefined) {
     return;
-  } else if (nextSegment(EXISTS)) {
-    const value = applySegment(subject, segment, cursor);
-    _remove(nextSegment, value, append(segment, cursor));
-  } else if (!isScalar(subject)) {
-    delete subject[segment];
-  } else {
-    applySegment(subject, segment, cursor);
   }
+
+  // lastSubject could also be an array, but this appeases the type system
+  delete /** @type API.JsonObject */ (lastSubject)[lastSegment];
 };
 
-export const append = curry((segment, pointer) => pointer + "/" + escape(segment));
+/** @type API.append */
+export const append = (segment, pointer) => pointer + "/" + escape(segment);
 
+/** @type (segment: string) => string */
 const escape = (segment) => segment.toString().replace(/~/g, "~0").replace(/\//g, "~1");
+
+/** @type (segment: string) => string */
 const unescape = (segment) => segment.toString().replace(/~1/g, "/").replace(/~0/g, "~");
-const computeSegment = (value, segment) => Array.isArray(value) && segment === "-" ? value.length : segment;
 
+/**
+ * @overload
+ * @param {API.Json[]} value
+ * @param {string} segment
+ * @returns {number}
+ *
+ * @overload
+ * @param {API.Json | undefined} value
+ * @param {string} segment
+ * @returns {string}
+ *
+ * @param {API.Json | undefined} value
+ * @param {string} segment
+ * @returns {string | number}
+ */
+const computeSegment = (value, segment) => {
+  if (Array.isArray(value)) {
+    return segment === "-" ? value.length : parseInt(segment, 10);
+  } else {
+    return segment;
+  }
+};
+
+/** @type (value: API.Json | undefined, segment: string, cursor?: string) => API.Json | undefined */
 const applySegment = (value, segment, cursor = "") => {
   if (value === undefined) {
     throw TypeError(`Value at '${cursor}' is undefined and does not have property '${segment}'`);
@@ -153,8 +314,12 @@ const applySegment = (value, segment, cursor = "") => {
     throw TypeError(`Value at '${cursor}' is a ${typeof value} and does not have property '${segment}'`);
   } else {
     const computedSegment = computeSegment(value, segment);
-    return value[computedSegment];
+    if (Object.hasOwn(value, computedSegment)) {
+      // value could also be an array, but this appeases the type system
+      return /** @type API.JsonObject */ (value)[computedSegment];
+    }
   }
 };
 
+/** @type (value: API.Json) => value is string | number | boolean | null */
 const isScalar = (value) => value === null || typeof value !== "object";

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@hyperjump/json-pointer",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "An RFC-6901 JSON Pointer implementation",
   "type": "module",
   "main": "./lib/index.js",
   "exports": "./lib/index.js",
   "scripts": {
-    "clean": "xargs -a .gitignore rm -rf",
     "lint": "eslint lib",
-    "test": "mocha 'lib/**/*.spec.ts'"
+    "test": "vitest --watch=false",
+    "type-check": "tsc --noEmit"
   },
   "repository": "github:hyperjump-io/json-pointer",
   "keywords": [
@@ -22,20 +22,11 @@
     "url": "https://github.com/sponsors/jdesrosiers"
   },
   "devDependencies": {
-    "@types/chai": "*",
-    "@types/mocha": "*",
-    "@typescript-eslint/eslint-plugin": "*",
-    "@typescript-eslint/parser": "*",
-    "chai": "*",
-    "eslint": "*",
-    "eslint-import-resolver-node": "*",
+    "@stylistic/eslint-plugin": "*",
+    "@types/node": "*",
     "eslint-import-resolver-typescript": "*",
     "eslint-plugin-import": "*",
-    "mocha": "*",
-    "ts-node": "*",
-    "typescript": "*"
-  },
-  "dependencies": {
-    "just-curry-it": "^5.3.0"
+    "typescript-eslint": "*",
+    "vitest": "*"
   }
 }

package/.github/FUNDING.yml

@@ -1 +0,0 @@
-github: [jdesrosiers]