From ca6ec5c2bce0b30dbc7e794a58eafeba5ab0f7a2 Mon Sep 17 00:00:00 2001 From: Daniel Lamando Date: Sat, 3 Oct 2020 17:18:33 +0200 Subject: [PATCH] Adapt README and switch GHA to deno --- .github/workflows/deno-ci.yml | 25 ++++++ .github/workflows/nodejs.yml | 29 ------- .github/workflows/npmpublish.yml | 48 ----------- README.md | 21 ++++- src/README.md | 140 +++++++++++++++++++++++++++++++ 5 files changed, 183 insertions(+), 80 deletions(-) create mode 100644 .github/workflows/deno-ci.yml delete mode 100644 .github/workflows/nodejs.yml delete mode 100644 .github/workflows/npmpublish.yml create mode 100644 src/README.md diff --git a/.github/workflows/deno-ci.yml b/.github/workflows/deno-ci.yml new file mode 100644 index 0000000..f12eadb --- /dev/null +++ b/.github/workflows/deno-ci.yml @@ -0,0 +1,25 @@ +name: Deno CI + +on: + push: + branches: [ main ] + pull_request: {} + +jobs: + build: + runs-on: ubuntu-latest + + name: Deno ${{ matrix.deno-version }} + strategy: + matrix: + deno-version: ["v1.x", "nightly"] + + steps: + - name: Checkout source + uses: actions/checkout@v2 + - name: Use Deno ${{ matrix.deno-version }} + uses: denolib/setup-deno@v2 + with: + deno-version: ${{ matrix.deno-version }} + - name: Run test suite + run: deno test --allow-read=test test/*.js diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml deleted file mode 100644 index e772a1c..0000000 --- a/.github/workflows/nodejs.yml +++ /dev/null @@ -1,29 +0,0 @@ -# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node -# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions - -name: Node.js CI - -on: - push: - branches: [ master ] - pull_request: - branches: [ master ] - -jobs: - build: - - runs-on: ubuntu-latest - - strategy: - matrix: - node-version: [10.x, 12.x] - - steps: - - uses: actions/checkout@v2 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v1 - with: - node-version: ${{ matrix.node-version }} - - run: npm ci - - run: npm run build --if-present - - run: npm test diff --git a/.github/workflows/npmpublish.yml b/.github/workflows/npmpublish.yml deleted file mode 100644 index ae508da..0000000 --- a/.github/workflows/npmpublish.yml +++ /dev/null @@ -1,48 +0,0 @@ -# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created -# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages - -name: Node.js Package - -on: - release: - types: [created] - -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v1 - with: - node-version: 12 - - run: npm ci - - run: npm test - - publish-npm: - needs: test - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v1 - with: - node-version: 12 - registry-url: https://registry.npmjs.org/ - - run: npm ci - - run: npm run build - - run: npm publish --verbose --access public --tag latest - env: - NODE_AUTH_TOKEN: ${{secrets.npm_token}} - -# publish-gpr: -# needs: build -# runs-on: ubuntu-latest -# steps: -# - uses: actions/checkout@v2 -# - uses: actions/setup-node@v1 -# with: -# node-version: 12 -# registry-url: https://npm.pkg.github.com/ -# - run: npm ci -# - run: npm publish -# env: -# NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/README.md b/README.md index f62fe3e..0504adb 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,22 @@ -![Node.js CI](https://github.com/nanoporetech/jmespath-ts/workflows/Node.js%20CI/badge.svg?branch=master) +![Test CI](https://github.com/danopia/deno-jmespath/workflows/Deno%20CI/badge.svg?branch=main) -# @metrichor/jmespath +# deno.land/x/jmespath +A jmespath-ts fork, repackaged and ported to Deno. +The `src/` directory is published to deno.land. +The `test/` directory contains the upstream unit tests. +All other files and directories are unused leftovers from upstream. + +This library should be useful for JSON-heavy APIs such as AWS. + +In the process of porting, +I changed the AST types to leverage descriminated unions, +in order to reduce usage of casts and any. +The original library used a tsconfig to disable some implicit-any checks +which isn't acceptable in deno libraries. + + +# Original README below @metrichor/jmespath is a **typescript** implementation of the [JMESPath](https://jmespath.org) spec. @@ -114,7 +129,7 @@ Extend the list of built in JMESpath expressions with your own functions. ``` -### `compile(expression: string): ExpressionNodeTree` +### `compile(expression: string): ASTNode` You can precompile all your expressions ready for use later on. the `compile` function takes a JMESPath expression and returns an abstract syntax tree that diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..bb16427 --- /dev/null +++ b/src/README.md @@ -0,0 +1,140 @@ +# jmespath + +This is a TypeScript implementation of the [JMESPath](https://jmespath.org) spec, +ported to the Deno runtime. +The original TypeScript implementation comes from +[nanoporetech/jmespath-ts](https://github.com/nanoporetech/jmespath-ts). + +JMESPath is a query language for JSON. It will take a JSON document +as input and transform it into another JSON document +given a JMESPath expression. + +## USAGE + +### `search(data: JSONValue, expression: string): JSONValue` + +```javascript +import { search } from "https://deno.land/x/jmespath/index.ts"; + +search({foo: {bar: {baz: [0, 1, 2, 3, 4]}}}, "foo.bar.baz[2]") + +// OUTPUTS: 2 + +``` + +In the example we gave the `search` function input data of +`{foo: {bar: {baz: [0, 1, 2, 3, 4]}}}` as well as the JMESPath +expression `foo.bar.baz[2]`, and the `search` function evaluated +the expression against the input data to produce the result `2`. + +The JMESPath language can do *a lot* more than select an element +from a list. Here are a few more examples: + +```javascript +import { search } from "https://deno.land/x/jmespath/index.ts"; + +/* --- EXAMPLE 1 --- */ + +let JSON_DOCUMENT = { + foo: { + bar: { + baz: [0, 1, 2, 3, 4] + } + } +}; + +search(JSON_DOCUMENT, "foo.bar"); +// OUTPUTS: { baz: [ 0, 1, 2, 3, 4 ] } + + +/* --- EXAMPLE 2 --- */ + +JSON_DOCUMENT = { + "foo": [ + {"first": "a", "last": "b"}, + {"first": "c", "last": "d"} + ] +}; + +search(JSON_DOCUMENT, "foo[*].first") +// OUTPUTS: [ 'a', 'c' ] + + +/* --- EXAMPLE 3 --- */ + +JSON_DOCUMENT = { + "foo": [ + {"age": 20}, + {"age": 25}, + {"age": 30}, + {"age": 35}, + {"age": 40} + ] +} + +search(JSON_DOCUMENT, "foo[?age > `30`]"); +// OUTPUTS: [ { age: 35 }, { age: 40 } ] +``` + + +### `registerFunction(functionName: string, customFunction: RuntimeFunction, signature: InputSignature[]): void` + +Extend the list of built in JMESpath expressions with your own functions. + +```javascript + import {search, registerFunction, TYPE_NUMBER} from "https://deno.land/x/jmespath/index.ts"; + + + search({ foo: 60, bar: 10 }, 'divide(foo, bar)') + // THROWS ERROR: Error: Unknown function: divide() + + registerFunction( + 'divide', // FUNCTION NAME + (resolvedArgs) => { // CUSTOM FUNCTION + const [dividend, divisor] = resolvedArgs; + return dividend / divisor; + }, + [{ types: [TYPE_NUMBER] }, { types: [TYPE_NUMBER] }] //SIGNATURE + ); + + search({ foo: 60,bar: 10 }, 'divide(foo, bar)'); + // OUTPUTS: 6 + +``` + +### `compile(expression: string): ASTNode` + +You can precompile all your expressions ready for use later on. the `compile` +function takes a JMESPath expression and returns an abstract syntax tree that +can be used by the TreeInterpreter function + +```javascript +import { compile, TreeInterpreter } from "https://deno.land/x/jmespath/index.ts"; + +const ast = compile('foo.bar'); + +TreeInterpreter.search(ast, {foo: {bar: 'BAZ'}}) +// RETURNS: "BAZ" + +``` + + +## More Resources + +The example above only show a small amount of what +a JMESPath expression can do. If you want to take a +tour of the language, the *best* place to go is the +[JMESPath Tutorial](http://jmespath.org/tutorial.html). + +One of the best things about JMESPath is that it is +implemented in many different programming languages including +python, ruby, php, lua, etc. To see a complete list of libraries, +check out the [JMESPath libraries page](http://jmespath.org/libraries.html). + +And finally, the full JMESPath specification can be found +on the [JMESPath site](http://jmespath.org/specification.html). + + +## License + +jmespath-ts is licensed under the Mozilla Public License Version 2.0