feat: 🎸 add initial implementation

Author: streamich

package.json

@@ -40,12 +40,12 @@
     "format:write": "biome format --write ./src",
     "lint": "biome lint ./src",
     "lint:fix": "biome lint --apply ./src",
-    "clean": "npx rimraf lib typedocs coverage gh-pages yarn-error.log",
+    "clean": "npx rimraf@6.0.1 lib typedocs coverage gh-pages yarn-error.log",
     "build": "tsc --project tsconfig.build.json --module commonjs --target es2020 --outDir lib",
-    "test": "vitest /src",
+    "test": "vitest ./src",
     "coverage": "yarn test --collectCoverage",
     "typedoc": "npx typedoc@0.25.13 --tsconfig tsconfig.build.json",
-    "build:pages": "npx rimraf@5.0.5 gh-pages && mkdir -p gh-pages && cp -r typedocs/* gh-pages && cp -r coverage gh-pages/coverage",
+    "build:pages": "npx rimraf@6.0.1 gh-pages && mkdir -p gh-pages && cp -r typedocs/* gh-pages && cp -r coverage gh-pages/coverage",
     "deploy:pages": "gh-pages -d gh-pages",
     "publish-coverage-and-typedocs": "yarn typedoc && yarn coverage && yarn build:pages && yarn deploy:pages"
   },
@@ -56,8 +56,10 @@
     "@jsonjoy.com/util": "^1.3.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^1.9.3",
     "@types/benchmark": "^2.1.5",
     "benchmark": "^2.1.4",
+    "config-galore": "^1.0.0",
     "tslib": "^2.7.0",
     "typescript": "^5.6.2",
     "vitest": "^2.1.2"

src/__bench__/find.js

@@ -0,0 +1,58 @@
+const Benchmark = require('benchmark');
+const {parseJsonPointer} = require('../../../es6/json-pointer');
+const {find} = require('../../../es6/json-pointer/find');
+const {parseJsonPointer: parseJsonPointerEs5} = require('../../../lib/json-pointer');
+const {find: findEs5} = require('../../../lib/json-pointer/find');
+const {findByPointer: findByPointerV1} = require('../../../es6/json-pointer/findByPointer/v1');
+const {findByPointer: findByPointerV2} = require('../../../es6/json-pointer/findByPointer/v2');
+const {findByPointer: findByPointerV3} = require('../../../es6/json-pointer/findByPointer/v3');
+const {findByPointer: findByPointerV4} = require('../../../es6/json-pointer/findByPointer/v4');
+const {findByPointer: findByPointerV5} = require('../../../es6/json-pointer/findByPointer/v5');
+const {findByPointer: findByPointerV6} = require('../../../es6/json-pointer/findByPointer/v6');
+
+const suite = new Benchmark.Suite();
+
+const doc = {
+  foo: {
+    bar: [
+      {
+        baz: 123,
+      },
+    ],
+  },
+};
+
+suite
+  .add(`find`, function () {
+    const pointer = parseJsonPointer('/foo/bar/0/baz');
+    find(doc, pointer);
+  })
+  .add(`find ES5`, function () {
+    const pointer = parseJsonPointerEs5('/foo/bar/0/baz');
+    findEs5(doc, pointer);
+  })
+  .add(`findByPointer (v1)`, function () {
+    findByPointerV1('/foo/bar/0/baz', doc);
+  })
+  .add(`findByPointer (v2)`, function () {
+    findByPointerV2('/foo/bar/0/baz', doc);
+  })
+  .add(`findByPointer (v3)`, function () {
+    findByPointerV3('/foo/bar/0/baz', doc);
+  })
+  .add(`findByPointer (v4)`, function () {
+    findByPointerV4('/foo/bar/0/baz', doc);
+  })
+  .add(`findByPointer (v5)`, function () {
+    findByPointerV5('/foo/bar/0/baz', doc);
+  })
+  .add(`findByPointer (v6)`, function () {
+    findByPointerV6('/foo/bar/0/baz', doc);
+  })
+  .on('cycle', function (event) {
+    console.log(String(event.target));
+  })
+  .on('complete', function () {
+    console.log('Fastest is ' + this.filter('fastest').map('name'));
+  })
+  .run();

src/__bench__/parseJsonPointer.ts

@@ -0,0 +1,30 @@
+/* tslint:disable no-console */
+
+import * as Benchmark from 'benchmark';
+import {parseJsonPointer} from '../util';
+
+const suite = new Benchmark.Suite();
+
+suite
+  .add(`parseJsonPointer ""`, () => {
+    parseJsonPointer('');
+  })
+  .add(`parseJsonPointer "/"`, () => {
+    parseJsonPointer('/');
+  })
+  .add(`parseJsonPointer "/foo"`, () => {
+    parseJsonPointer('/foo');
+  })
+  .add(`parseJsonPointer "/foo/bar/baz"`, () => {
+    parseJsonPointer('/foo/bar/baz');
+  })
+  .add(`parseJsonPointer "/foo/bar/baz/layer~0/123/ok~1test/4"`, () => {
+    parseJsonPointer('/foo/bar/baz/layer~0/123/ok~1test/4');
+  })
+  .on('cycle', (event: any) => {
+    console.log(String(event.target));
+  })
+  .on('complete', () => {
+    console.log('Fastest is ' + suite.filter('fastest').map('name'));
+  })
+  .run();

src/__demos__/json-pointer.ts

@@ -0,0 +1,33 @@
+/* tslint:disable no-console */
+
+/**
+ * Run this demo with:
+ *
+ *     npx ts-node src/json-pointer/__demos__/json-pointer.ts
+ */
+
+import {find, unescapeComponent, escapeComponent, parseJsonPointer, formatJsonPointer} from '../../json-pointer';
+
+const doc = {
+  foo: {
+    bar: 123,
+  },
+};
+
+const path = parseJsonPointer('/foo/bar');
+const ref = find(doc, path);
+
+console.log(ref);
+// { val: 123, obj: { bar: 123 }, key: 'bar' }
+
+console.log(parseJsonPointer('/f~0o~1o/bar/1/baz'));
+// [ 'f~o/o', 'bar', '1', 'baz' ]
+
+console.log(formatJsonPointer(['f~o/o', 'bar', '1', 'baz']));
+// /f~0o~1o/bar/1/baz
+
+console.log(unescapeComponent('~0~1'));
+// ~/
+
+console.log(escapeComponent('~/'));
+// ~0~1

src/__tests__/find.spec.ts

@@ -0,0 +1,4 @@
+import {find} from '../find';
+import {testFindRef} from './testFindRef';
+
+testFindRef(find);

src/__tests__/testFindRef.ts

@@ -0,0 +1,112 @@
+import {test, expect} from 'vitest';
+import {Path, Reference} from '..';
+import {isArrayReference, isArrayEnd} from '../find';
+import {parseJsonPointer} from '../util';
+
+export const testFindRef = (find: (val: unknown, path: Path) => Reference) => {
+  test('can find number root', () => {
+    const res = find(123, []);
+    expect(res.val).toBe(123);
+  });
+
+  test('can find string root', () => {
+    const res = find('foo', []);
+    expect(res.val).toBe('foo');
+  });
+
+  test('can find key in object', () => {
+    const res = find({foo: 'bar'}, ['foo']);
+    expect(res.val).toBe('bar');
+  });
+
+  test('returns container object and key', () => {
+    const res = find({foo: {bar: {baz: 'qux', a: 1}}}, ['foo', 'bar', 'baz']);
+    expect(res).toEqual({
+      val: 'qux',
+      obj: {baz: 'qux', a: 1},
+      key: 'baz',
+    });
+  });
+
+  test('can reference simple object key', () => {
+    const doc = {a: 123};
+    const path = parseJsonPointer('/a');
+    const res = find(doc, path);
+    expect(res).toEqual({
+      val: 123,
+      obj: {a: 123},
+      key: 'a',
+    });
+  });
+
+  test('throws when referencing missing key with multiple steps', () => {
+    const doc = {a: 123};
+    const path = parseJsonPointer('/b/c');
+    expect(() => find(doc, path)).toThrow(new Error('NOT_FOUND'));
+  });
+
+  test('can reference array element', () => {
+    const doc = {a: {b: [1, 2, 3]}};
+    const path = parseJsonPointer('/a/b/1');
+    const res = find(doc, path);
+    expect(res).toEqual({
+      val: 2,
+      obj: [1, 2, 3],
+      key: 1,
+    });
+  });
+
+  test('can reference end of array', () => {
+    const doc = {a: {b: [1, 2, 3]}};
+    const path = parseJsonPointer('/a/b/-');
+    const ref = find(doc, path);
+    expect(ref).toEqual({
+      val: undefined,
+      obj: [1, 2, 3],
+      key: 3,
+    });
+    expect(isArrayReference(ref)).toBe(true);
+    if (isArrayReference(ref)) expect(isArrayEnd(ref)).toBe(true);
+  });
+
+  test('throws when pointing past array boundary', () => {
+    const doc = {a: {b: [1, 2, 3]}};
+    const path = parseJsonPointer('/a/b/-1');
+    expect(() => find(doc, path)).toThrow(new Error('INVALID_INDEX'));
+  });
+
+  test('can point one element past array boundary', () => {
+    const doc = {a: {b: [1, 2, 3]}};
+    const path = parseJsonPointer('/a/b/3');
+    const ref = find(doc, path);
+    expect(ref).toEqual({
+      val: undefined,
+      obj: [1, 2, 3],
+      key: 3,
+    });
+    expect(isArrayReference(ref)).toBe(true);
+    if (isArrayReference(ref)) expect(isArrayEnd(ref)).toBe(true);
+  });
+
+  test('can reference missing object key', () => {
+    const doc = {foo: 123};
+    const path = parseJsonPointer('/bar');
+    const ref = find(doc, path);
+    expect(ref).toEqual({
+      val: undefined,
+      obj: {foo: 123},
+      key: 'bar',
+    });
+  });
+
+  test('can reference missing array key withing bounds', () => {
+    const doc = {foo: 123, bar: [1, 2, 3]};
+    const path = parseJsonPointer('/bar/3');
+    const ref = find(doc, path);
+    expect(ref).toEqual({
+      val: undefined,
+      obj: [1, 2, 3],
+      key: 3,
+    });
+  });
+};

src/__tests__/util.escapeComponent.spec.ts

@@ -0,0 +1,11 @@
+import {test, expect} from 'vitest';
+import {escapeComponent} from '../util';
+
+test('string without escaped characters as is', () => {
+  const res = escapeComponent('foobar');
+  expect(res).toBe('foobar');
+});
+
+test('replaces special characters', () => {
+  expect(escapeComponent('foo~/')).toBe('foo~0~1');
+});

src/__tests__/util.formatJsonPointer.spec.ts

@@ -0,0 +1,27 @@
+import {test, expect} from 'vitest';
+import {formatJsonPointer} from '../util';
+
+test('returns path without escaped characters parsed into array', () => {
+  const res = formatJsonPointer(['foo', 'bar']);
+  expect(res).toBe('/foo/bar');
+});
+
+test('empty string elements add trailing slashes', () => {
+  const res = formatJsonPointer(['foo', '', '', '']);
+  expect(res).toBe('/foo///');
+});
+
+test('array with single empty string results into root element', () => {
+  const res = formatJsonPointer([]);
+  expect(res).toBe('');
+});
+
+test('two empty strings result in a single slash "/"', () => {
+  const res = formatJsonPointer(['']);
+  expect(res).toBe('/');
+});
+
+test('escapes special characters', () => {
+  const res = formatJsonPointer(['a~b', 'c/d', '1']);
+  expect(res).toBe('/a~0b/c~1d/1');
+});

src/__tests__/util.isChild.spec.ts

@@ -0,0 +1,32 @@
+import {test, expect} from 'vitest';
+import {isChild} from '../util';
+
+test('returns false if parent path is longer than child path', () => {
+  const res = isChild(['', 'foo', 'bar', 'baz'], ['', 'foo']);
+  expect(res).toBe(false);
+});
+
+test('returns true for real child', () => {
+  const res = isChild(['', 'foo'], ['', 'foo', 'bar', 'baz']);
+  expect(res).toBe(true);
+});
+
+test('returns false for different root steps', () => {
+  const res = isChild(['', 'foo'], ['', 'foo2', 'bar', 'baz']);
+  expect(res).toBe(false);
+});
+
+test('returns false for adjacent paths', () => {
+  const res = isChild(['', 'foo', 'baz'], ['', 'foo', 'bar']);
+  expect(res).toBe(false);
+});
+
+test('returns false for two roots', () => {
+  const res = isChild([''], ['']);
+  expect(res).toBe(false);
+});
+
+test('always returns true when parent is root and child is not', () => {
+  const res = isChild([''], ['', 'a', 'b', 'c', '1', '2', '3']);
+  expect(res).toBe(true);
+});

src/__tests__/util.parent.spec.ts

@@ -0,0 +1,12 @@
+import {test, expect} from 'vitest';
+import {parent} from '../util';
+
+test('returns parent path', () => {
+  expect(parent(['foo', 'bar', 'baz'])).toEqual(['foo', 'bar']);
+  expect(parent(['foo', 'bar'])).toEqual(['foo']);
+  expect(parent(['foo'])).toEqual([]);
+});
+
+test('throws when path has no parent', () => {
+  expect(() => parent([])).toThrow(new Error('NO_PARENT'));
+});