Skip to content

inkandswitch/cambria-project

default
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Cambria

Cambria is a Javascript/Typescript library for converting JSON data between related schemas.

You specify (in YAML or JSON) a lens, which specifies a data transformation. Cambria lets you use this lens to convert:

Lenses are bidirectional. Once you've converted a document from schema A to schema B, you can edit the document in schema B and propagate those edits backwards through the same lens to schema A.

For more background on why Cambria exists and what it can do, see the research essay.

Cambria is still immature software, and isn't yet ready for production use

Use cases

  • Manage backwards compatibility in a JSON API
  • Manage database migrations for JSON data
  • Transform a JSON document into a different shape on the command line
  • Combine with cambria-automerge to collaborate on documents across multiple versions of local-first software

CLI Usage

Cambria includes a simple CLI tool for converting JSON from the command line.

(You'll want to run yarn build to compile the latest code.)

Covert the github issue into a an arthropod-style issue:

cat ./demo/github-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml

To get a live updating pipeline using entr:

echo ./demo/github-arthropod.lens.yml | entr bash -c "cat ./demo/github-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml > ./demo/simple-issue.json"

Compile back from an updated "simple issue" to a new github issue file:

cat ./demo/simple-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml -r -b ./demo/github-issue.json

Live updating pipeline backwards:

echo ./demo/simple-issue.json | entr bash -c "cat ./demo/simple-issue.json | node ./dist/cli.js -l ./demo/github-arthropod.lens.yml -r -b ./demo/github-issue.json > ./demo/new-github-issue.json"

API Usage

Cambria is mostly intended to be used as a Typescript / Javascript library. Here's a simple example of converting an entire document.

// read doc from stdin if no input specified
const input = readFileSync(program.input || 0, 'utf-8')
const doc = JSON.parse(input)

// we can (optionally) apply the contents of the changed document to a target document
const targetDoc = program.base ? JSON.parse(readFileSync(program.base, 'utf-8')) : {}

// now load a (yaml) lens definition
const lensData = readFileSync(program.lens, 'utf-8')
let lens = loadYamlLens(lensData)

// should we reverse this lens?
if (program.reverse) {
  lens = reverseLens(lens)
}

// finally, apply the lens to the document, with the schema, onto the target document!
const newDoc = applyLensToDoc(lens, doc, program.schema, targetDoc)
console.log(JSON.stringify(newDoc, null, 4))

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).

Tests

npm run test

About

Schema evolution with bi-directional lenses.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •