• Stars
    star
    616
  • Rank 72,837 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 4 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Schema evolution with bi-directional lenses.

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

More Repositories

1

peritext

A CRDT for asynchronous rich-text collaboration, where authors can work independently and then merge their changes.
TypeScript
654
star
2

farm

🌱 Grow delightful software
Elm
249
star
3

tiny-essay-editor

simple markdown editor w inline comments, on latest automerge stack
TypeScript
214
star
4

livebook

IPython notebook-compatible live coding experiment
Python
200
star
5

capstone

An experimental, tablet-based tool for developing your ideas
TypeScript
175
star
6

potluck

TypeScript
74
star
7

ksp-browser

Connect the things you already know in your browser.
TypeScript
71
star
8

backchannel

Local-first address book
TypeScript
67
star
9

ksp

Reference implementation of Knowledge Server Protocol (KSP)
Rust
48
star
10

backchat

A relationship-based digital identity system.
TypeScript
31
star
11

vscode-hypermerge

A VSCode plugin to edit Hypermerge documents
TypeScript
28
star
12

upwelling-code

The Upwelling research prototype.
TypeScript
23
star
13

interactive-shape-recognition

Implementaion of "A Simple Approach to Recognise Geometric Shapes Interactively" by Joaquim A. Jorge and Manuel J. Fonseca.
JavaScript
18
star
14

eup-experiment-pipes

JavaScript
16
star
15

flutter-hello

A sample flutter drawing app
Objective-C
16
star
16

cambria-automerge

TypeScript
16
star
17

here

resilient location sharing
TypeScript
12
star
18

inkling

archived prototype for sketching dynamic models
TypeScript
8
star
19

automerge-todomvc-http

An automerge TodoMVC interop demo
Rust
5
star
20

cambria-express

use cambria to migrate API requests as express middleware
TypeScript
5
star
21

farm-peer

A cloud peer for farm to keep data warm while your computer is sleeping.
TypeScript
4
star
22

discovery-cloud-client

TypeScript
4
star
23

Inkteractions

JavaScript
1
star