{"id":15681493,"url":"https://github.com/sagold/json-pointer","last_synced_at":"2025-05-07T18:09:20.762Z","repository":{"id":26876557,"uuid":"73638221","full_name":"sagold/json-pointer","owner":"sagold","description":"Failsafe value retrieval, modification and utils using json-pointer spec","archived":false,"fork":false,"pushed_at":"2025-02-15T14:46:54.000Z","size":497,"stargazers_count":11,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T08:17:59.864Z","etag":null,"topics":["failsafe","json-pointer","modify","retrieve","rfc-6901"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sagold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-13T19:37:37.000Z","updated_at":"2025-02-15T14:46:58.000Z","dependencies_parsed_at":"2024-06-18T17:04:42.279Z","dependency_job_id":"b66faab6-be5e-4a7d-a698-bc984dae54f9","html_url":"https://github.com/sagold/json-pointer","commit_stats":{"total_commits":124,"total_committers":4,"mean_commits":31.0,"dds":"0.16129032258064513","last_synced_commit":"cc6adbc0ea6611201de6eb8bad635680f3d5e80d"},"previous_names":["sagold/gson-pointer"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-pointer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-pointer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-pointer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-pointer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sagold","download_url":"https://codeload.github.com/sagold/json-pointer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252703613,"owners_count":21790916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["failsafe","json-pointer","modify","retrieve","rfc-6901"],"created_at":"2024-10-03T16:55:34.204Z","updated_at":"2025-05-07T18:09:20.698Z","avatar_url":"https://github.com/sagold.png","language":"TypeScript","readme":"\u003ch1 align=\"left\"\u003e\u003cimg src=\"./docs/sagold-json-pointer.png\" width=\"100%\" alt=\"@sagold/json-pointer\"\u003e\u003c/h1\u003e\n\n\u003cp align=\"left\"\u003e\u003cb\u003ejson-pointer implementation following \u003ca href=\"https://tools.ietf.org/html/rfc6901\"\u003eRFC 6901\u003c/a\u003e to work with serializable paths into javascript data structures.\u003c/b\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#api\"\u003eapi\u003c/a\u003e | \u003ca href=\"#usage-examples\"\u003eusage examples\u003c/a\u003e | \u003ca href=\"#fragment-identifier\"\u003efragment identifier\u003c/a\u003e | \u003ca href=\"#breaking-changes\"\u003ebreaking changes\u003c/a\u003e\n\u003c/p\u003e \n\n**install**\n\n`yarn add @sagold/json-pointer`\n\n**usage**\n\n```js\nimport { get, set, remove } from '@sagold/json-pointer';\nconst data = {};\n\nget(data, '/path/to/nested/item'); // undefined\nset(data, '/path/to/nested/item', 123); // { path: { to: { nested: { item: 123 }}}\nremove(data, '/path/to/nested/item'); // { path: { to: { nested: { }}}\n```\n\n\n## API\n\nAs the _error handling_ is not further specified, this implementation will return `undefined` for any invalid\npointer/missing data, making it very convenient to work with uncertain data.\n\n| method                                    | description\n| ----------------------------------------- | -------------------------------------------------------------\n| get(data, pointer) -\u003e value               | returns the value at given pointer\n| set(data, pointer, value) -\u003e data         | sets the value at the given path\n| remove(data, pointer) -\u003e data             | removes a property from data\n| join(...pointers) -\u003e pointer              | joins multiple pointers to a single one\n| split(pointer) -\u003e [array]                 | returns a json-pointer as an array\n| splitLast(pointer) -\u003e [pointer, property] | returns parent-pointer and last property\n\n\n\u003e The methods `get`, `set`, `remove` and `join` also accept a list of properties as pointer. Using join with a list\n\u003e of properties, its signature changes to `join(properties:string[], isURI=false) -\u003e string`\n\n\n## Usage Examples\n\n### get\n\n\u003e get(data:object|array, pointer:string|array, defaultValue:any) -\u003e value:any\n\nreturns nested values\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst data = {\n    parent: {\n        child: {\n            title: 'title of child'\n        }\n    }\n}\n\nconst titleOfChild = pointer.get(data, '/parent/child/title'); // output: 'title of child'\nconsole.log(pointer.get(data, '/parent/missing/path')); // output: undefined\n```\n\nand may optionally return a default value with\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst value = pointer.get({}, \"/invalid/value\", 42);\nconsole.log(value); // output: 42\n```\n\n`get` also accepts a list of properties as pointer (e.g. split-result)\n\n```js\nconst titleOfChild = pointer.get(data, ['parent', 'child', 'title']); // output: 'title of child'\nconsole.log(pointer.get(data, ['parent', 'missing', 'path'])); // output: undefined\n```\n\n### set\n\n\u003e set(data:object|array, pointer:string|array, value:any) -\u003e data:object|array\n\nchanges a nested value\n\n```js\nimport pointer from '@sagold/json-pointer';\n\nvar data = {\n    parent: {\n        children: [\n            {\n                title: 'title of child'\n            }\n        ]\n    }\n};\n\npointer.set(data, '/parent/children/1', { title: 'second child' });\nconsole.log(data.parent.children.length); // output: 2\n```\n\nand may be used to build data\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst data = pointer.set({}, '/list/[]/value', 42);\nconsole.log(data); // output: { list: [ { value: 42 } ] }\n```\n\n`set` also accepts a list of properties as pointer (e.g. split-result)\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst data = pointer.set({}, ['list', '[]', 'value'], 42);\nconsole.log(data); // output: { list: [ { value: 42 } ] }\n```\n\n#### behaviour using `set`\n\n`set` will **create arrays** when encountering a number\n\n```js\npointer.set({}, ['list', '1', 'value'], 42);\n// { list: [undefined, { value: 42 }] }\n```\n\nalternatively you may use array-syntax `[index]`\n\n```js\npointer.set({}, ['list', '[1]', 'value'], 42);\n// { list: [undefined, { value: 42 }] }\n```\n\n**append items** using empty array syntax `[]`\n\n```js\npointer.set({ list: [1, 2] }, ['list', '[]', 'value'], 42);\n// { list: [1, 2, { value: 42 }] }\n```\n\n**create object** using object syntax `{index}`\n\n```js\npointer.set({}, ['list', '{1}', 'value'], 42);\n// { list: { 1: { value: 42 } }\n```\n\n\u003e ⚠️ `set` prefers existing data-type over specified data-types. For example: Setting an object for an existing array, will keep the object intact:\n\u003e\n\u003e ```js\n\u003e pointer.set({ list: []}, ['list', '{0}', 'value'], 42);\n\u003e // { list: [{ value: 42 }] }\n\u003e ```\n\n\n### remove\n\n\u003e remove(data:object|array, pointer:string|array) -\u003e data:object|array\n\ndeletes a nested property or item\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst data = pointer.remove({ parent: { arrayOrObject: [ 0, 1 ] }}, '/parent/arrayOrObject/1');\nconsole.log(data.parent.arrayOrObject); // output: [0]\n```\n\n`remove` also accepts a list of properties as pointer (e.g. split-result)\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst data = pointer.remove({ parent: { arrayOrObject: [ 0, 1 ] }}, ['parent', 'arrayOrObject', '1']);\nconsole.log(data.parent.arrayOrObject); // output: [0]\n```\n\n\n### split\n\n\u003e split(pointer:string) -\u003e properties:array\n\nreturns a json-pointer as a list of (escaped) properties\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst list = pointer.split('/parent/arrayOrObject/1');\nconsole.log(list); // output: ['parent', 'arrayOrObject', '1']\n```\n\nIn order to resolve a list of properties, you can directly pass the list to `get`, `set` or `remove`\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst data = { a: { b: true } };\nconst list = pointer.split('/a/b');\nconsole.log(pointer.get(data, list)); // output: true\n```\n\n\n### splitLast\n\n\u003e splitLast(pointer:string) -\u003e [pointer, property]\n\nseparates json-pointers last property and returns both values as [parent-pointer, property]\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst [parent, property] = pointer.splitLast('/parent/arrayOrObject/1');\nconsole.log(parent); // output: '/parent/arrayOrObject'\nconsole.log(property); // output: '1'\n```\n\n\n### join\n\n\u003e join(...pointers:string[]) -\u003e pointer:string\n\njoins all arguments to a valid json pointer\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst key = 'my key';\nconsole.log(pointer.join('root', key, '/to/target')); // output: '/root/my key/to/target'\n```\n\nand joins relative pointers as expected\n\n```js\nimport pointer from '@sagold/json-pointer';\nconsole.log(pointer.join('/path/to/value', '../object')); // output: '/path/to/object'\n```\n\nin order to join an array received from split, you can use `join(properties:string[], isURI=false) -\u003e string` to\nretrieve a valid pointer\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst list = pointer.split('/my/path/to/child');\nlist.pop();\nconsole.log(pointer.join(list)); // output: '/my/path/to'\n```\n\nTo join an array of pointers, you must use it with `join(...pointers)` or all pointers will be treated as properties:\n\n```js\nimport pointer from '@sagold/json-pointer';\nconst path = pointer.join(...['/path/to/value', '../object']);\nconsole.log(path); // output: '/path/to/object'\n\n// passing the array directly, will treat each entry as a property, which will be escaped and resolves to:\npointer.join(['/path/to/value', '../object']); // output: '/~1path~1to~1value/..~1object'\n```\n\n\n## Fragment identifier\n\nAll methods support a leading uri fragment identifier (#), which will ensure that property-values are uri decoded\nwhen resolving the path within data. This also ensures that any pointer is returned uri encoded with a leading `#`. e.g.\n\n```js\nimport pointer from '@sagold/json-pointer';\n\n// get\nconst value = pointer.get({ 'my value': true }, '#/my%20value');\nconsole.log(value); // output: true\n\n// join\nconst pointer = pointer.join('#/my value/to%20parent', '../to~1child');\nconsole.log(pointer); // output: '#/my%20value/to~1child'\n\n// join an array of properties\nconst uriPointer = pointer.join(['my value', 'to~1child'], isURI = true);\nconsole.log(uriPointer); // output: '#/my%20value/to~1child'\n```\n\nAdditionally `join(...pointers, isURI)` may be used to enforce the pointer type, which is helpful in sanitizing inputs\n\n```js\nconst uriPointer = pointer.join('my pointer', 'to', 'property', isURI = true);\nconsole.log(uriPointer); // output: '#/my%20pointer/to/property'\n\nconst uriSimple = pointer.join('/my pointer/to/property', isURI = true);\nconsole.log(uriSimple); // output: '#/my%20pointer/to/property'\n\nconst pointer = pointer.join('#/my pointer', 'to', 'property', isURI = false);\nconsole.log(pointer); // output: '/my pointer/to/property'\n```\n\n\n## Breaking Changes\n\n- 2025/01/14 with `v7`\n    - `pointer.set` creates arrays using numbers as properties `/1` when the data is null or an array (previously created objects)\n    - `pointer.set` creates objects for numbers when using object-syntax `/{1}` (previously unsupported)\n- 2024/04/06 with `v6`, selection of empty properties is supported:\n    -  `\"/\"` now selects an empty property (previously root-pointer)\n    -  `\"a//b\"` is now a valid pointer to `\"a\" » \"\" » \"b\"`\n    - `join` no longer removes double slashes when joining `join(\"/a/\", \"/b\")` » `\"/a//b\"`\n- 2022/12/02 with `v5`, package has been renamed to `json-pointer` and published under `@sagold/json-pointer`\n- 2020/11/09 with `v4`, `pointer.delete` has been renamed to `remove`","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsagold%2Fjson-pointer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsagold%2Fjson-pointer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsagold%2Fjson-pointer/lists"}