version-repo
Advanced tools
A suite of repositories with semantic versioning of objects and their dependencies. Think Bower, but for anything, not just JS code
You've got lots of things (code, data, whatever), and you've got multiple versions of your things. Furthermore your things only work when paired with the right versions of other things.
Version-repo's are typed repositories that store named values, their version, and their requirements (dependencies). Version repo's take care of the logic of finding a complete and consistent set of resources for a given query.
Furthermore, there are a variety of version-repo's which simplify the process of storing your object on disk, in memory, or in a database; serving and querying them http/https, and perfomning tranformations when storing and/or fetching your resources (e.g. stringifying / parsing JSON objects stored on disk).
Resources are stored using the create() method, like so:
var R = require("version-repo");
var repo = new R.MemoryRepo();
repo.create({name:"A",version:"v1.1.1",value:"My great thing"});
repo.create({name:"A",version:"v1.1.2",value:"An even better thing"});
repo.create({name:"A",version:"v1.1.5",value:"The best thing yet"});
repo.create({name:"A",version:"2.0.0", value:"Something different"});
Resources are queried using the fetch() method, which return an array of matching resources.
repo.fetch({name:"A"});
// [{ name: "A",
// version: "2.0.0",
// value: "Something different" }]
Note that because we didn't specify a version, the latest version of the resource was returned
In the event that you really only want the specified resource and not the
dependencies, the fetchOne() method will do the trick:
repo.fetchOne([{name:"A"}]);
// { name: "A",
// version: "2.0.0",
// value: "Something different" }
older versions of a resource can be queried by passing a version parameter:
repo.fetch([{name:"A",version:"1.1.1"}]).value // "My great thing"
and we can use the a query object of for as shorthand for an array of name/version pairs:
repo.fetch({"A":"1.1.1"}).value // "My great thing"
repo.fetch({"A":"1.1.1"}).value // "My great thing"
repo.fetch({"A":"1.1.x"}).value // "The best thing yet"
repo.fetch({"A":"~1"}).value // "The best thing yet"
repo.fetch({"A":"1.1.3 - 1.1.7 || >=2.5.0"}).value // "The best thing yet"
So far we've stored several vesions of a single resource, but the real purpose of the version repo's is to manage multiple resources and their versions. For this, we'll neeed a more complicated example:
repo.create({name:"A",version:"1.0.0",value:"abc"});
repo.create({name:"A",version:"1.1.1",value:"Abc"});
repo.create({name:"A",version:"1.1.2",value:"aBc"});
repo.create({name:"A",version:"1.1.3",value:"abC"});
repo.create({name:"A",version:"1.2.3",value:"ABc"});
repo.create({name:"A",version:"2.0.0",value:"ABC"});
repo.create({name:"B",version:"1.0.0",value:"def",depends:{"A":"~1.0.0"});
repo.create({name:"B",version:"1.1.1",value:"Def",depends:{"A":"~1.1.1"});
repo.create({name:"B",version:"1.1.3",value:"DEf",depends:{"A":"1.1.2"});
repo.create({name:"B",version:"1.1.4",value:"DEF",depends:{"A":"~2.0.0"});
repo.create({name:"C",version:"1.0.0",value:"efg");
repo.create({name:"C",version:"1.1.1",value:"Efg",depends:{"B":"~1.1.1"});
repo.create({name:"C",version:"1.1.2",value:"EFg",depends:{"B":"~1.1.2"});
repo.create({name:"C",version:"1.1.3",value:"EFg",depends:{"B":"1.1.1","A":"2.0.0"}); // this set of requirements are in conflict...
repo.create({name:"C",version:"1.1.4",value:"efG",depends:{"B":"~1.1.3"});
with our more mature repository, we can query the complete set of resources
that are required for by our query using the feth() method:
repo.fetch([{name:"B",version:"1.1.4"}])
similarly, the depends() method will return list of resources which match
your query, (but not the resources themselves...)
// Calculate dependencies
repo.depends({B:"1.1.4"}) // {A:"2.0.0",B:"1.1.4",}
repo.depends({B:"1.1.4",C:"1.1.1"}) // {A:"2.0.0",B:"1.1.4",C:"1.1.1"}
and to get the list of resources, and their dependencies, but not the values,
we can pass an options object to fetch, specifying the novealue:true
repo.fetch({B:"1.1.4"},{novalue:true})
Conveniently, attempting to fetch an conflicted set of resources throws a
Version Conflict error, when there is no set of resources
which satisfies your query:
// Each of these raises a Version Conflict error
repo.dependencies([{"B":"1.1.1"},{"A":"2.0.0"}])
repo.fetch([{"B":"1.1.1"},{"A":"2.0.0"}])
repo.fetch([{"C":"1.1.3"}])
A resource either can be updated using either update() method or the
insert() method with the option upsert:true:
repo.update({name:'A',version:'2.0.0',value:"something else"})
repo.insert({name:'A',version:'2.0.0',value:"something else",upsert:true})
However by default you may only update the latest version of the resource,
which can be changed by setting update:"any" or update:"none" when
instantiating the repo.
A resource can be deleted using the del() method:
repo.del({name:'A',version:'2.0.0'})
However by default you may only delete the latest version of the resource,
which can be changed by setting delete:"any" or delete:"none" when
instantiating the repo.
A synchronous repository which keeps resources in memory.
var my_repo = new MemoryRepo()
A ReadOnly Buffer repository is a read-only wrapper which keeps local copies of resources queried from another 'host' repository. This is particularly useful if the host repo is on another physical machine, for example to reduce the number of network requests of mobile apps. Local resources are stored in memory and calls to create/update/delete methods are forwarded onto the host repository.
var host_repo = new MemoryRepo()
var my_readonly_repo =new ReadonlyBuffer(host_repo)
A Synchronous repo which forwards all requests to another version repo and performs transformations of the stored values on create / update (storifying) and fetch (de-storifying).
This is particularly useful for wrapping string-only repositories, such as the
FileRepo in the
version-repo-node package,
with parse-on-read and stringify-on-write logic. Another use case is for
storing and dispatching copies of objects stored in a repo, in whicn case one
of the many deep-copy functions may be used for storifying, and de-storifiying
values. Transformers could also provide validate-on-save logic by using an
object validator such as the awesome AJV library as a storify, and trivial
function for destorifying (e.g. function(x){return x;})
S.create()ed) or updated.fetch()ed).var host_repo = new MemoryRepo()
var my_repo = new sTransform(host_repo,JSON.stringify,JSON.parse)
the same examlple in TypeScript with generic typing:
var host_repo = new MemoryRepo<string>()
var my_repo = new sTransform<string,any>(host_repo,JSON.stringify,JSON.parse)
An asynchronous (i.e. Deffered) repo which forwards all requests to another version repo and performs transformations of the objects in transit.
This is particularly useful for wrapping asynchronous repo's with limited storage types, such as the File and Remote (HTTP/S) Repo's in version-repo-node)
S.funciton(x:T):S)funciton(x:T):S)Note that the host repo may have a synchronous API, and the storify and/or de-storify functions may return transformed values or Promised for the transformed values.
var string_only_repo = new MemoryRepo()
var my_async_repo = new dTransform(string_only_repo,JSON.stringify,JSON.parse)
the same examlple in TypeScript with generic types:
var string_only_repo = new MemoryRepo<string>()
var my_async_repo = new dTransform<string,any>(string_only_repo,JSON.stringify,JSON.parse)
Every repo's that can potentially store any type of object accept a type parameter:
import { MemoryRepo } from "version-repo"
const my_string_repo = new MemoryRepo<string>()
and synchronous and deferred transform repositories accept two type parameters which specify the type of the underlying repo, and the type for the API it exposes. In this example, a FileRepo is used to store serialized objects on disk, and an deferred transform repo is used to manage the serialization / de-serialization:
repo: new repo.sTransform(new repo.MemoryRepo(), (x => x), (x => x))});
import { sTransform } from "version-repo"
import { FileRepo } from "version-repo-node"
const my_file_repo = new FileRepo({directory:"/some/place/nice")}) // a string only repo.
const my_object_store = new sTransform<string,any>( my_file_repo JSON.stringify, JSON.parse);
Some repo's can store only a limited set of values, eg. the FileRepo can only accept sting values.
This package is written in typescripts so explicitly importing .d.ts file should not be required.
However generic repo interfaces are defined in src/typings.d.ts, and the
synchronous API is provided here for tautological purposes:
// an object type used for queries:
export interface package_loc { name:string; version?:string; }
// an object type used for creating and updating resources
export interface resource_data<T> {
name:string;
version:string;
value?:T; // yes it's optional. (i.e. when `fetch_opts.novalue = true`)
depends?:{[key:string]:string};
upsert?:boolean
force?:boolean
}
// the synchronous repo interface
interface sync_repository<T> {
// CRUD:
create(resource:resource_data<T>):boolean; // return indicates succes / failure
update(resource:resource_data<T>):boolean; // return indicates succes / failure
del(query:package_loc):boolean; // return indicates succes / failure
// fetch a set of mathing resource
fetch(query:package_loc|package_loc[],
fetch_opts?:fetch_opts):resource_data<T>[];
// fetch a single resource
fetchOne(query:package_loc,
opts?:fetch_opts):resource_data<T>;
// returns a list of name
depends(query:package_loc|package_loc[]|{[key: string]:string}):package_loc[];
// ENUMERATION:
packages():string[] ; // returns a list of resource names
// return a list of available versions of a named resource
versions():{[x:string]:string[]};
// return a list of available versions of a named resource
versions(name:string):string[];
// returns the lastest version of a named resource
latest_version(name:string):string
}
Method signatures are the same as the synchronous versions, but return a bluebird promise for each return value.
Note that these examples also demonstrate version-repo-node and make use of temp
// Create an in-memory versioned repository
var repo = require('versioned-repo'),
my_mem_repo= repo.memory(),
// Create a repo using the local file system (NodeJS)
var temp = require('temp'), // requires npm install temp
path = require('path'),
node_repo = require('versioned-repo-node'),
temp_dir = temp.mkdirSync(),
my_file_repo = node_repo.file({directory:path.join(temp_dir,"my_repo_files")}),
// Wrap the file system repo in a read-only buffer
var buffered_file_repo = repo.readonly_buffer(my_file_repo);
// Expose the buffered file repo via an Express HTTP server
var express = require('express'),
app = express();
app.use('/my_repo',
repo.router({
repository:buffered_file_repo,
version_repo:my_mem_repo,
}));
var server = ('function' === typeof app) ? http.createServer(app) : app;
server.listen(0);
// Create a "remote" repo which provides access to the express router router via http:
var address = server.address();
if (!address) {
server.listen(0);
address = server.address();
}
var protocol = (server instanceof https.Server) ? 'https:' : 'http:';
var hostname = address.address;
if (hostname === '0.0.0.0' || hostname === '::') {
hostname = '127.0.0.1';
}
var base_url = protocol + '//' + hostname + ':' + address.port ;
var remote_repo = new repo.remote({
'base_url':base_url + '/my_repo',
})
// Create a transformer which transforms strings from the remote repo to JSON
// objects (and back, when storing objects):
json_repo = dTransform(// d is for deferred
remote_repo,
JSON.stringify, // for storing objects
JSON.parse); // for parsing stored strings
// ----------------------
// Now some actual CRUD
// ----------------------
// store a string in the file-system based repo
my_file_repo.creae({name:"my-resource",version:"1.2.3"},
'{"hello":"world"}'
).then(() => {
// then fetch it from the JSON repo
return json_repo.fetch({name:"my-resource",version:"^1.x"});
}).then((resource) => {
console.log(resource.object); // eventually logs: { hello: 'world' }
console.log(resource.version); // eventually logs: '1.2.3'
// enumerate packages
return json_repo.packages();
}).then((resources) => {
console.log(resources); // eventually logs: [ 'my-resource' ]
// get the latest version of a package
return json_repo.latest_version();
}).then((version) => {
console.log(version); // eventually logs: '1.2.3'
// get the latest version of a package
return json_repo.versions();
}).then((versions) => {
console.log(versions); // eventually logs: [ '1.2.3' ]
// Calculate the set of matching dependencies for an array of required objects.
// (This is admittedly a trivial example, see the test files for more complex examples):
return calculate_dependencies([ {name:"my-resource",version:"^1.0.0"}, ],json_repo);
}).then((dependents) => {
console.log(dependents); // eventually logs: [ { name: 'my-resource', version: '1.2.3' } ]
})
FAQs
A set of versioned data-stores
The npm package version-repo receives a total of 1 weekly downloads. As such, version-repo popularity was classified as not popular.
We found that version-repo demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.