From 5e87db001a45b8db45eba2f9c83d5a47882f1940 Mon Sep 17 00:00:00 2001 From: Tim Caswell Date: Thu, 2 Jan 2014 16:42:58 -0600 Subject: [PATCH] Save doc changes --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- js-git.js | 8 +++++++- mixins/objects.js | 47 +++++++++++++++++------------------------------ 3 files changed, 68 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 3215ae7..28812f8 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,50 @@ This project is very modular and configurable by gluing different components tog This repo, `js-git`, is the core implementation of git and consumes various instances of interfaces. This means that your network and persistance stack is completely pluggable. -If you're looking for a more pre-packaged system, consider packages like `creationix/git-node` that implement all the abstract interfaces using node.js native APIs. The `creationix/jsgit` package is an example of a CLI tool that consumes this. +The old interface from milestone #1 has been deprecated and a new modular interface is in progress as part of milestone #2. + +In the new system, you can build your js-git repo instance piecemeal or use the default config that expects a db interface instance as input. + +The built-in mixins are `objects`, `refs`, `walkers`, `packops`, `client`, and `server`. + +The default exports looks something like this: + +```js +function newRepo(db) { + var repo = {}; + repo.db = db; + require('./mixins/objects.js')(repo); + require('./mixins/refs.js')(repo); + require('./mixins/walkers.js')(repo); + require('./mixins/packops.js')(repo); + require('./mixins/client.js')(repo); + require('./mixins/server.js')(repo); + return repo; +} +``` + +As you can see the mixing expect to be passed a repo instance and add methods to it. This flexibility allows projects like [js-github][] exist that re-implement the `objects` and `refs` mixins, but still use the rest of the code as-is. + +## Objects interface + +This interface is responsible for loading and saving git objects to and from a storage backend. In the default implementation it assumes `repo.db` implements the abstract db interface, but you can replace this with your own implementation for more flexilibity. + +### repo.load(hash-ish) -> {type,body} + +### repo.save({type,body}) -> hash + +### repo.loadAs(type, hash-ish) -> body + +### repo.saveAs(type, body) -> hash + +### repo.loadRaw(hash) -> buffer + +### repo.saveRaw(hash, buffer) + +### repo.has(hash) -> boolean + +### repo.remove(hash) -The main end-user API as exported by this module for working with local repositories is: ## Initialize the library @@ -217,3 +258,4 @@ Being that js-git is so modular, here is a list of the most relevent modules tha - - A git-db implementation cased on `indexedDB`. [gen-run]: https://github.com/creationix/gen-run +[js-github]: https://github.com/creationix/js-github \ No newline at end of file diff --git a/js-git.js b/js-git.js index dc48018..e0a912b 100644 --- a/js-git.js +++ b/js-git.js @@ -10,7 +10,13 @@ function newRepo(db) { if (require('./lib/trace.js')) db = require('./lib/tracedb.js')(db); // Add the db interface (used by objects, refs, and packops mixins) - repo.db = db; + repo.remove = remove; + function remove(hash, callback) { + if (!callback) return remove.bind(this, hash); + var repo = this; + var db = repo.db; + return db.del(hash, callback); + } // Mix in object store interface require('./mixins/objects.js')(repo); diff --git a/mixins/objects.js b/mixins/objects.js index e2c545f..5c83e62 100644 --- a/mixins/objects.js +++ b/mixins/objects.js @@ -9,15 +9,24 @@ var isHash = require('../lib/ishash.js'); // Add "objects" capabilities to a repo using db as storage. module.exports = function (repo) { + if (typeof repo.loadRaw !== "function") { + throw new TypeError("OBJECTS mixin depends on repo.loadRaw(hash) -> buffer"); + } + if (typeof repo.saveRaw !== "function") { + throw new TypeError("OBJECTS mixin depends on repo.saveRaw(hash, buffer)"); + } + if (typeof repo.has !== "function") { + throw new TypeError("OBJECTS mixin depends on repo.has(hash) -> boolean"); + } + if (typeof repo.remove !== "function") { + throw new TypeError("OBJECTS mixin depends on repo.remove(hash)"); + } + // Add Object store capability to the system - repo.load = load; // (hash-ish) -> object - repo.save = save; // (object) -> hash - repo.loadRaw = loadRaw; // (hash) -> buffer - repo.saveRaw = saveRaw; // (hash, buffer) - repo.has = has; // (hash) -> true or false + repo.load = load; // (hash-ish) -> {type,value} + repo.save = save; // ({type,value}) -> hash repo.loadAs = loadAs; // (type, hash-ish) -> value repo.saveAs = saveAs; // (type, value) -> hash - repo.remove = remove; // (hash) // This is a fallback resolve in case there is no refs system installed. if (!repo.resolve) repo.resolve = function (hash, callback) { @@ -31,13 +40,12 @@ function load(hashish, callback) { if (!callback) return load.bind(this, hashish); var hash; var repo = this; - var db = repo.db; return repo.resolve(hashish, onHash); function onHash(err, result) { if (result === undefined) return callback(err); hash = result; - return db.get(hash, onBuffer); + return repo.loadRaw(hash, onBuffer); } function onBuffer(err, buffer) { @@ -61,23 +69,10 @@ function load(hashish, callback) { } } -function loadRaw(hash, callback) { - return this.db.get(hash, callback); -} - -function saveRaw(hash, buffer, callback) { - return this.db.set(hash, buffer, callback); -} - -function has(hash, callback) { - return this.db.has(hash, callback); -} - function save(object, callback) { if (!callback) return save.bind(this, object); var buffer, hash; var repo = this; - var db = repo.db; try { buffer = encoders[object.type](object.body); buffer = frame(object.type, buffer); @@ -86,7 +81,7 @@ function save(object, callback) { catch (err) { return callback(err); } - return db.set(hash, buffer, onSave); + return repo.saveRaw(hash, buffer, onSave); function onSave(err) { if (err) return callback(err); @@ -94,14 +89,6 @@ function save(object, callback) { } } -function remove(hash, callback) { - if (!callback) return remove.bind(this, hash); - if (!isHash(hash)) return callback(new Error("Invalid hash: " + hash)); - var repo = this; - var db = repo.db; - return db.del(hash, callback); -} - function loadAs(type, hashish, callback) { if (!callback) return loadAs.bind(this, type, hashish); return this.load(hashish, onObject);