{"id":25596848,"url":"https://github.com/nanoporetech/jmespath-plus","last_synced_at":"2025-04-13T02:31:13.403Z","repository":{"id":42745402,"uuid":"268086685","full_name":"nanoporetech/jmespath-plus","owner":"nanoporetech","description":"JMESPath with extended collection of built-in functions","archived":false,"fork":false,"pushed_at":"2023-01-07T04:50:30.000Z","size":691,"stargazers_count":14,"open_issues_count":7,"forks_count":0,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-06T08:02:14.573Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nanoporetech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-30T13:38:03.000Z","updated_at":"2024-03-20T11:56:30.000Z","dependencies_parsed_at":"2023-02-06T12:16:54.346Z","dependency_job_id":null,"html_url":"https://github.com/nanoporetech/jmespath-plus","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fjmespath-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fjmespath-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fjmespath-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoporetech%2Fjmespath-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nanoporetech","download_url":"https://codeload.github.com/nanoporetech/jmespath-plus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248657795,"owners_count":21140841,"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":[],"created_at":"2025-02-21T12:34:47.491Z","updated_at":"2025-04-13T02:31:13.370Z","avatar_url":"https://github.com/nanoporetech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Node.js CI](https://github.com/nanoporetech/jmespath-plus/workflows/Node.js%20CI/badge.svg?branch=master)\n\n# @metrichor/jmespath-plus\n\n\n@metrichor/jmespath-plus extends [@metrichor/jmespath](https://www.npmjs.com/package/@metrichor/jmespath) with `lodash` functions that map well to JSON objects as well as a few extra typed functions that are native to this library.\n\nJMESPath is a query language for JSON. It will take a JSON document\nas input and transform it into another JSON document\ngiven a JMESPath expression.\n\nWhere this library departs is by adding a number of extra functions to the JMESPath expressions that are helpful if you require more powerful JSON transforms of simpler expressions.\n\n---\n\n## INSTALLATION\n\n```\nnpm i @metrichor/jmespath-plus\n```\n\n---\n\n## JMESPATH BUILT-INS\n\nThe current [JMESPath spec](https://jmespath.org/specification.html#built-in-functions) already describes a number of built-in functions that my be sufficient. These are already included in this library\n\n---\n\n## __JMESPATH-PLUS__ EXTENSIONS\n\n  - `as_lambda` - Convert strings to anonymous functions to be used as lodash predicates\n  - `as_regexp` - Convert strings to `Regexp` objects to be used as lodash arguments\n  - `toJSON` - Convert JS objects to JSON strings\n  - `fromJSON` - Convert JSON strings to JS objects\n  - `mean` - Calculate the mean/average of an array of numbers\n  - `mode` - Calculate the most common number in an array of numbers\n  - `median` - Calculate the middle value from an array of numbers\n  - `toFixed` - Set the precision of a float\n  - `formatNumber` - Format a number with units at a set precision\n  - `uniq` - De-duplicate a list of values\n  - `mod` - Calculate the modulus of two numbers\n  - `divide` - Divide two numbers\n  - `split` - Split a string on a given character or character sequence\n  - `entries` - Flatten a hash into key, value tuples\n  - `format` - Format a string given a template and input values (array/object)\n  - `flatMapValue` - Flatten all values in a object into key, value tuples\n  - `toUpperCase` - Uppercase (locale based) all characters in a string\n  - `toLowerCase` - Lowercase (locale based) all characters in a string\n  - `trim` - Remove flanking whitespace from a string\n  - `groupBy` - Group an array of objects by a value or expression\n  - `combine` - Create an object from a tuple of key, value pairs (inverse of entries)\n\n---\n\n## __LODASH__ EXTENSIONS\n\nMost Lodash functions that apply to JSON types are included as JMESPath function expressions and are __prefixed with an `_` character__ to ensure no name clashes and overwrites with the built-in functions.\n\nFor example the [lodash zip] function:\n\n```tsx\n/* In Javascript this looks as follows... */\n\n_.zip(['a', 'b'], [1, 2], [true, false]);\n// =\u003e [['a', 1, true], ['b', 2, false]]\n\n\n/* In JMESPath however, this looks as follows... */\n\nsearch([['a', 'b'], [1, 2], [true, false]], '_zip([0], [1], [2])')\n\n// =\u003e [['a', 1, true], ['b', 2, false]]\n\n```\n\n**`NOT ALL LODASH FUNCTIONS HAVE BEEN INCLUDED!!!!`**\n\nMany lodash functions don't necessarily map to JSON objects. For a complete list of the __`165 lodash`__ functions that are included in jmespath-plus go [HERE](./LODASH_SUPPORT.md)\n\n### DEALING WITH PREDICATES\n\nMany lodash functions accept function predicates as arguments. This is still possible in jmespath-plus by using a new built-in function that converts strings to functions (`as_lambda`). For example:\n\n```javascript\n\n// `_findKey` JMESPath function extension\n\nconst { search }  = require('@metrichor/jmespath-plus');\n\nconst users = {\n  barney: { age: 36, active: true },\n  fred: { age: 40, active: false },\n  pebbles: { age: 1, active: true },\n};\n\nassert(search(users, \"_findKey(@, as_lambda('o =\u003e o.age \u003c 40'))\") === 'barney');\n\n```\n\n---\n\n## USAGE\n\n### `search(data: JSONValue, expression: string): JSONValue`\n\n```javascript\n/* using ES modules */\nimport { search } from '@metrichor/jmespath-plus';\n\n\n/* using CommonJS modules */\nconst search = require('@metrichor/jmespath-plus').search;\n\n\nsearch({foo: {bar: {baz: [0, 1, 2, 3, 4]}}}, \"foo.bar.baz[2]\")\n\n// OUTPUTS: 2\n\n```\n\nIn the example we gave the `search` function input data of\n`{foo: {bar: {baz: [0, 1, 2, 3, 4]}}}` as well as the JMESPath\nexpression `foo.bar.baz[2]`, and the `search` function evaluated\nthe expression against the input data to produce the result `2`.\n\nThe JMESPath language can do *a lot* more than select an element\nfrom a list.  Here are a few more examples:\n\n```javascript\nimport { search } from '@metrichor/jmespath-plus';\n\n/* --- EXAMPLE 1 --- */\n\nlet JSON_DOCUMENT = {\n  foo: {\n    bar: {\n      baz: [0, 1, 2, 3, 4]\n    }\n  }\n};\n\nsearch(JSON_DOCUMENT, \"foo.bar\");\n// OUTPUTS: { baz: [ 0, 1, 2, 3, 4 ] }\n\n\n/* --- EXAMPLE 2 --- */\n\nJSON_DOCUMENT = {\n  \"foo\": [\n    {\"first\": \"a\", \"last\": \"b\"},\n    {\"first\": \"c\", \"last\": \"d\"}\n  ]\n};\n\nsearch(JSON_DOCUMENT, \"foo[*].first\")\n// OUTPUTS: [ 'a', 'c' ]\n\n\n/* --- EXAMPLE 3 --- */\n\nJSON_DOCUMENT = {\n  \"foo\": [\n    {\"age\": 20},\n    {\"age\": 25},\n    {\"age\": 30},\n    {\"age\": 35},\n    {\"age\": 40}\n  ]\n}\n\nsearch(JSON_DOCUMENT, \"foo[?age \u003e `30`]\");\n// OUTPUTS: [ { age: 35 }, { age: 40 } ]\n```\n\n\n### `registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void`\n\nExtend the list of built in JMESpath expressions with your own functions.\n\n```javascript\n  import {search, registerFunction, TYPE_NUMBER} from '@metrichor/jmespath-plus'\n\n\n  search({ foo: 60, bar: 10 }, 'divide(foo, bar)')\n  // THROWS ERROR: Error: Unknown function: divide()\n\n  registerFunction(\n    'divide', // FUNCTION NAME\n    (resolvedArgs) =\u003e {   // CUSTOM FUNCTION\n      const [dividend, divisor] = resolvedArgs;\n      return dividend / divisor;\n    },\n    [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER] }] //SIGNATURE\n  );\n\n  search({ foo: 60,bar: 10 }, 'divide(foo, bar)');\n  // OUTPUTS: 6\n\n```\n\n### `compile(expression: string): ExpressionNodeTree`\n\nYou can precompile all your expressions ready for use later on. the `compile`\nfunction takes a JMESPath expression and returns an abstract syntax tree that\ncan be used by the TreeInterpreter function\n\n```javascript\nimport { compile, TreeInterpreter } from '@metrichor/jmespath';\n\nconst ast = compile('foo.bar');\n\nTreeInterpreter.search(ast, {foo: {bar: 'BAZ'}})\n// RETURNS: \"BAZ\"\n\n```\n\n## More Resources\n\nThe example above only show a small amount of what\na JMESPath expression can do. If you want to take a\ntour of the language, the *best* place to go is the\n[JMESPath Tutorial](http://jmespath.org/tutorial.html).\n\nOne of the best things about JMESPath is that it is\nimplemented in many different programming languages including\npython, ruby, php, lua, etc.  To see a complete list of libraries,\ncheck out the [JMESPath libraries page](http://jmespath.org/libraries.html).\n\nAnd finally, the full JMESPath specification can be found\non the [JMESPath site](http://jmespath.org/specification.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoporetech%2Fjmespath-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnanoporetech%2Fjmespath-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoporetech%2Fjmespath-plus/lists"}