@hyperjump/json-pointer 1.1.0 → 1.1.2

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/lib/index.d.ts

@@ -1,53 +1,40 @@
-export const nil: "";
-export const pointerSegments: (pointer: string) => Generator<string>;
-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,7 +1,16 @@
+/** @import * as API from "./index.d.ts" */
+
+
+/** @type API.nil */
 export const nil = "";
 
+/** @type API.pointerSegments */
 export const pointerSegments = function* (pointer) {
-  if (pointer.length > 0 && pointer[0] !== "/") {
+  if (pointer.length > 0 && !pointer.startsWith("/")) {
+    throw Error("Invalid JSON Pointer");
+  }
+
+  if (/~(?![01])/.test(pointer)) {
     throw Error("Invalid JSON Pointer");
   }
 
@@ -18,6 +27,22 @@ export const pointerSegments = function* (pointer) {
   }
 };
 
+/**
+ * @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) => {
   if (subject === undefined) {
     const segments = [...pointerSegments(pointer)];
@@ -27,7 +52,9 @@ export const get = (pointer, subject = undefined) => {
   }
 };
 
+/** @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);
@@ -37,15 +64,33 @@ const _get = (segments, subject) => {
   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) => {
   if (subject === undefined) {
-    const segments = [...pointerSegments(pointer)];
-    return (subject, value) => _set(segments.values(), subject, value);
+    return (subject, value) => _set(pointerSegments(pointer), subject, value);
   } else {
-    return _set(pointerSegments(pointer), subject, value);
+    return _set(pointerSegments(pointer), subject, /** @type API.Json */ (value));
   }
 };
 
+/** @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) {
@@ -61,45 +106,96 @@ const _set = (segments, subject, value, cursor = nil) => {
   }
   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);
-  subject[computedSegment] = _set(segments, subject[computedSegment], value, cursor);
-  return subject;
+  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) => {
   if (subject === undefined) {
-    const segments = [...pointerSegments(pointer)];
-    return (subject, value) => _assign(segments.values(), subject, value);
+    return (subject, value) => _assign(pointerSegments(pointer), subject, value);
   } else {
-    return _assign(pointerSegments(pointer), subject, value);
+    return _assign(pointerSegments(pointer), subject, /** @type API.Json */ (value));
   }
 };
 
+/** @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(subject, segment);
+    segment = computeSegment(currentSubject, segment);
     lastSegment = segment;
-    lastSubject = subject;
-    subject = applySegment(subject, segment, cursor);
+    lastSubject = currentSubject;
+    currentSubject = applySegment(currentSubject, segment, cursor);
     cursor = append(segment, cursor);
   }
 
-  if (lastSubject !== undefined) {
-    lastSubject[lastSegment] = value;
+  if (lastSegment === undefined) {
+    return;
   }
+
+  // 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) => {
   if (subject === undefined) {
-    const segments = [...pointerSegments(pointer)];
-    return (subject) => _unset(segments.values(), subject);
+    return (subject) => _unset(pointerSegments(pointer), subject);
   } else {
     return _unset(pointerSegments(pointer), subject);
   }
 };
 
+/**
+ * @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) {
@@ -115,45 +211,104 @@ const _unset = (segments, subject, cursor = nil) => {
   }
   cursor = append(segment.value, cursor);
 
-  const computedSegment = computeSegment(subject, segment.value);
-  const unsetSubject = _unset(segments, subject[computedSegment], cursor);
-  if (computedSegment in subject) {
-    subject[computedSegment] = unsetSubject;
+  // 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 subject;
+  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) => {
   if (subject === undefined) {
-    const segments = [...pointerSegments(pointer)];
-    return (subject) => _remove(segments.values(), subject);
+    return (subject) => _remove(pointerSegments(pointer), subject);
   } else {
     return _remove(pointerSegments(pointer), subject);
   }
 };
 
+/** @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(subject, segment);
+    segment = computeSegment(currentSubject, segment);
     lastSegment = segment;
-    lastSubject = subject;
-    subject = applySegment(subject, segment, cursor);
+    lastSubject = currentSubject;
+    currentSubject = applySegment(currentSubject, segment, cursor);
     cursor = append(segment, cursor);
   }
 
-  if (lastSubject !== undefined) {
-    delete lastSubject[lastSegment];
+  if (lastSegment === undefined) {
+    return;
   }
+
+  // lastSubject could also be an array, but this appeases the type system
+  delete /** @type API.JsonObject */ (lastSubject)[lastSegment];
 };
 
+/** @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}'`);
@@ -163,8 +318,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.1.0",
+  "version": "1.1.2",
   "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": "vitest --watch=false"
+    "test": "vitest --watch=false",
+    "type-check": "tsc --noEmit"
   },
   "repository": "github:hyperjump-io/json-pointer",
   "keywords": [
@@ -22,13 +22,11 @@
     "url": "https://github.com/sponsors/jdesrosiers"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "*",
-    "@typescript-eslint/parser": "*",
-    "eslint": "*",
-    "eslint-import-resolver-node": "*",
+    "@stylistic/eslint-plugin": "*",
+    "@types/node": "*",
     "eslint-import-resolver-typescript": "*",
     "eslint-plugin-import": "*",
-    "typescript": "*",
+    "typescript-eslint": "*",
     "vitest": "*"
   }
 }

package/.github/FUNDING.yml

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