diff --git a/README.md b/README.md index 0fe3cf7..f2ade62 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,234 @@ const newDoc = applyLensToDoc(lens, doc, program.schema, targetDoc) console.log(JSON.stringify(newDoc, null, 4)) ``` +## Lens Operations + +### add(name, type) + +Add a field +Example lens file: + +```yml +- add: + name: completed + type: boolean +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug"}' | node ./dist/cli.js -l ./examples/add.yml +{ + "title": "Found a bug", + "completed": false +} +``` + +### remove(name) + +Remove a field +Example lens file: + +```yml +- remove: { name: completed } +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug","completed":true}' | node ./dist/cli.js -l ./examples/remove.yml +{ + "title": "Found a bug" +} +``` + +### rename(source, destination) + +Rename a field +Example: + +```yml +- rename: + source: title + destination: name +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug"}' | node ./dist/cli.js -l ./examples/rename.yml +{ + "name": "Found a bug" +} +``` + +### hoist(name, host) + +Pull a field out of an object +Example: + +```yml +- hoist: + name: login + host: user +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug", "user":{"login":"octocat"}}' | node ./dist/cli.js -l ./examples/hoist.yml +{ + "title": "Found a bug", + "user": {}, + "login": "octocat" +} +``` + +### plunge(name, host) + +Move a field into an existing object +Example: + +```yml +- add: + name: user + type: object +- plunge: + name: login + host: user +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug", "login":"octocat"}' | node ./dist/cli.js -l ./examples/plunge.yml +{ + "title": "Found a bug", + "user": { + "login": "octocat" + } +} +``` + +### head(name) + +Replace an array field by its first element +Example: + +```yml +- head: { name: assignee } +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug", "assignee":["octocat", "someone"]}' | node ./dist/cli.js -l ./examples/head.yml +{ + "title": "Found a bug", + "assignee": "octocat" +} +``` + +### wrap(name) + +Replace a scalar field by an array containing it as its only element +Example: + +```yml +- wrap: { name: assignee } +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug", "assignee":"octocat"}' | node ./dist/cli.js -l ./examples/wrap.yml +{ + "title": "Found a bug", + "assignee": [ + "octocat" + ] +} +``` + +### in(name, lens) + +Apply a lens inside an object +Example: + +```yml +- in: + name: user + lens: + - remove: + name: login +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug", "user":{"login":"octocat"}}' | node ./dist/cli.js -l ./examples/in.yml +{ + "title": "Found a bug", + "user": {} +} +``` + +### map(lens) + +In an array, apply a lens to each item + +```yml +- in: + name: assignees + lens: + - map: + lens: + - add: + name: admin + type: boolean +``` + +Effect: + +```sh +$ echo '{"title":"Found a bug", "assignees":[{"login":"octocat"}]}' | node ./dist/cli.js -l ./examples/map.yml +{ + "title": "Found a bug", + "assignees": [ + { + "login": "octocat", + "admin": false + } + ] +} +``` + +### convert(name, mapping) + +Convert an enumerable field to another set of values +Example: + +````yml +- convert: + name: status + mapping: + # old to new + - open: todo + closed: done + # new to old + - todo: open + doing: open + done: closed +``` +Effect: +```sh +$ echo '{"title":"Found a bug", "status":"open"}' | node ./dist/cli.js -l ./examples/convert.yml +{ + "title": "Found a bug", + "status": "todo" +} +```` + ## Install If you're using npm, run `npm install cambria`. If you're using yarn, run `yarn add cambria`. Then you can import it with `require('cambria')` as in the examples (or `import * as Cambria from 'cambria'` if using ES2015 or TypeScript). diff --git a/examples/add.yml b/examples/add.yml new file mode 100644 index 0000000..bc2a05f --- /dev/null +++ b/examples/add.yml @@ -0,0 +1,4 @@ +lens: + - add: + name: completed + type: boolean diff --git a/examples/convert.yml b/examples/convert.yml new file mode 100644 index 0000000..b2cd111 --- /dev/null +++ b/examples/convert.yml @@ -0,0 +1,11 @@ +lens: + - convert: + name: status + mapping: + # old to new + - open: todo + closed: done + # new to old + - todo: open + doing: open + done: closed diff --git a/examples/extract.yml b/examples/extract.yml new file mode 100644 index 0000000..156b709 --- /dev/null +++ b/examples/extract.yml @@ -0,0 +1,10 @@ +lens: + - extract: + host: orders + name: customers + fields: + - customer_name + - customer_address + options: + deduplicate: true + identifier: autoincrement diff --git a/examples/head.yml b/examples/head.yml new file mode 100644 index 0000000..b9465e4 --- /dev/null +++ b/examples/head.yml @@ -0,0 +1,2 @@ +lens: + - head: { name: assignee } diff --git a/examples/hoist.yml b/examples/hoist.yml new file mode 100644 index 0000000..cf4e4f0 --- /dev/null +++ b/examples/hoist.yml @@ -0,0 +1,4 @@ +lens: + - hoist: + name: login + host: user diff --git a/examples/in.yml b/examples/in.yml new file mode 100644 index 0000000..09b5a59 --- /dev/null +++ b/examples/in.yml @@ -0,0 +1,6 @@ +lens: + - in: + name: user + lens: + - remove: + name: login diff --git a/examples/map.yml b/examples/map.yml new file mode 100644 index 0000000..2c94ce6 --- /dev/null +++ b/examples/map.yml @@ -0,0 +1,9 @@ +lens: + - in: + name: assignees + lens: + - map: + lens: + - add: + name: admin + type: boolean diff --git a/examples/plunge.yml b/examples/plunge.yml new file mode 100644 index 0000000..1cdb6a7 --- /dev/null +++ b/examples/plunge.yml @@ -0,0 +1,7 @@ +lens: + - add: + name: user + type: object + - plunge: + name: login + host: user diff --git a/examples/remove.yml b/examples/remove.yml new file mode 100644 index 0000000..892dd42 --- /dev/null +++ b/examples/remove.yml @@ -0,0 +1,2 @@ +lens: + - remove: { name: completed } diff --git a/examples/rename.yml b/examples/rename.yml new file mode 100644 index 0000000..5cc4bab --- /dev/null +++ b/examples/rename.yml @@ -0,0 +1,4 @@ +lens: + - rename: + source: title + destination: name diff --git a/examples/wrap.yml b/examples/wrap.yml new file mode 100644 index 0000000..b09a1b9 --- /dev/null +++ b/examples/wrap.yml @@ -0,0 +1,2 @@ +lens: + - wrap: { name: assignee }