grand-central-records
Advanced tools
A basic ORM/ActiveRecord library for use in smaller Node projects or frameworks. Work in progress.
json — Database connection parameters.
string — An optional table name if only a single table is being queried.json — Options to pass to the model.
boolean function — Turning verbose on will log all queries on the console. false by default. If a function is provided, it will be used to log all outputs.string — The name of the unique ID attribute field (defaults to 'id');boolean — Set to true to map query results to a model. Otherwise, results will be in their raw format.Creating a new instance of the GCR object creates a connection to a new database.
var GCR = require('grand-central-records');
var Model = new GCR({
adapter: "mysql",
host: "localhost",
database: "test",
username: "admin",
password: "admin"
}, "users");
Model.find(8, function(err, user){
if (err) throw err;
console.log(user.name);
});
Model.select(["name","address"]).where({admin: true}, function(err, result) {
if (err) throw err;
result.forEach(function(user) {
...
});
});
string — The name of the table the model is associated with.json — See above.Multiple models can also be created from the same database.
var GCR = require('grand-central-records');
var db = new GCR({
adapter: "mysql",
host: "localhost",
database: "test",
username: "admin",
password: "admin"
}, { verbose: true });
var User = db.model("users"),
Project = db.model("projects");
Execute a query using a callback:
Model.find(52, function(err, res) {...});
Model.find(52).select('id').run(function(err, res) {...});
Or by using promises:
Model.find(52)
.then(function(res) {
return res;
})
.then(function(res) {
// do something...
})
.fail(function(err) {
throw err;
});
// Or in parallel using #parallel() as an alieas for Q's 'all'
db.parallel([
Model.find(52).run(),
Model.where({ type: 2 }).run()
]).done(function(res) {
// do something...
}).fail(function(err) {...});
Execute raw query to database.
db.query('SELECT 1 AS a', function(err, res) {
console.log(res[0].a); //= 1
});
// Substitute with array of values
db.query('SELECT 1 AS a; SELECT %1 AS a;', ['hello'], function(err, res) {
console.log(res[0].a); //= 1
console.log(res[1].a); //= hello
});
// Substitute with key/values
db.query('SELECT :name AS a', { name: 'hello' }, function(err, res) {
console.log(res[0].a); //= hello
})
Add query to queue for later execution. Query can be a raw query string, a chained method object, or an array of either. Values can't be passed to objects or arrays (only raw strings);
var queue = db.queue();
queue.add('SELECT 1 AS a')
.add('SELECT %1', [2])
.add('SELECT :name AS a', { name: 'hello' })
.run(function(err, res) {
console.log(res[0].a); //= 1
console.log(res[2].a); //= hello
});
queue.add(Model.find(1))
.add(Model.select('name').limit(1))
.run(function(err, res) {
console.log(res[0]); // (row with ID of 1)
console.log(res[1]); // (first row with only name column)
});
queue.add(['SELECT 1 AS a', 'SELECT 2 AS a']);
. . .
console.log(queue.print()); //= "SELECT 1 AS a; SELECT 2 AS a;"
queue.run(function(err, res) {
console.log(res[0].a); //= 1
console.log(res[1].a); //= 2
});
// OR as promise //
queue.run().then(function(res) {...})
.fail(function(err) {...});
// Add custom mapping function for results
queue.add(...).map(function(row) {
return row.id;
}).run();
To map query results to a model, define a schema for default values and validations. (To map results to a model without a schema, just define as an empty object schema: {}.)
var User = db.model('users', {
schema: {
first: String,
last: String,
admin: { type: Boolean, default: false },
created_at: Date,
updated_at: Date
}
});
type: type of input
StringNumberBooleanDateBuffer[value1, value2, value3, ...] list of options[String] array of values (Postgres only)default: default value if emptyallowNull: false requires a value (default is true)length: the maximum length of a stringmax: the maximum value of a number or length of a stringmin: the minimum value of a number or length of a stringnot: an array of incompatible valuesmatch: a RegEx the string must matchCustom Messages (%n replaced with required value):
wrongType: message if type doesn't matchtooShort: message if string/number is too lowtooLong: message if string/number is too highdoesntMatch: message if RegEx doesn't matchisNull: message if value is emptynotInList: message if value isn't in list of optionsinList: message if value is in list of incompatible valuesCreating a new model:
var tiger = Animal.new({ name: 'Tiger' });
// Run validations and insert into DB:
tiger.save(function(err) { ... });
// PROMISES //
tiger.save().then(function(err) { ... });
Updating a model:
Animal.where({ name: 'Tiger' }, function(err, animals) {
animals[0].name = 'Siberian Tiger';
// Run validations and update in DB:
animals[0].save(function(err) { ... });
});
// PROMISES //
Animal.where({ name: 'Tiger' }).then(function(animals) {
animals[0].name = 'Siberian Tiger';
return animals[0].save().run();
}).fail(function(err) { ... });
Methods are functions that can be called on the model.
var User = db.model('users', {
schema: {},
methods: {
add: function(n) {
return this.number + n;
}
}
});
. . .
console.log(user.number); //= 5
console.log(user.add(5)); //= 10
Getters are methods that are called immediately and act as regular values for a model. They can supplement or replace previous values.
var User = db.model('users', {
schema: {},
getters: {
first: function() { // No arguments
return this.first.toUpperCase();
},
fullName: function() {
return this.first + ' ' + this.last;
}
}
});
. . .
console.log(user.first); //= PETER
console.log(user.last); //= Parker
console.log(user.fullName); //= PETER Parker
Reloads the model's original data.
User.find(1, function(err, user) {
user.name = 'Mark';
console.log(user.name); //= Mark
user.reload();
console.log(user.name); //= Adam (the original)
});
Changes the table name of the database/model.
db.setTable('products');
// or
Products.setTable('products').find(1);
Gets all table rows (SELECT * FROM table).
int int[] — The ID, or an array of IDs, of the row(s) to return.Animal.find(88, function(err, animals) {
console.log(animals[0]); //= [{ id: 88, name: 'Tiger' }]
});
Animal.find([6, 18]);
string object — An expression string ("sales < 500 AND type = 'new'") or an object of property values to match ({ type: 'new' }).array object — Optional values to escape & substitute into expression string. An array of [0, 1, 2] replaces %1 %2 %3. An object of {a: 1, b: 2} replaces :a :b.Person.where("age >= 21");
//= SELECT * FROM people WHERE age >= 21;
Person.where({ gender: "female", hand: "left" });
//= SELECT * FROM people WHERE gender = 'female' AND hand = 'left';
Person.where("name = %1 OR name = %2", ['Jill', 'Jane']);
//= SELECT * FROM people WHERE name = 'Jill' OR name = 'Jane';
Person.where("age >= :age", { age: 21 });
//= SELECT * FROM people WHERE age >= 21;
// Subqueries (Postgres only):
Person.where({ id: Client.select('person_id').order('sales').limit(1) });
//= SELECT * FROM people WHERE id = (SELECT person_id FROM clients ORDER BY sales LIMIT 1);
string string[] — An array or comma-separated string of the columns you want returned.Book.select("author");
Book.select("author, publisher");
Book.select(["author", "publisher", "title"]);
string string[] — An array or comma-separated string of the columns (and optionally ASC/DESC) you want ordered.Animal.order('size');
Animal.order('size ASC, bones DESC');
Animal.order(['size', 'number']);
// Shortcuts
Animal.orderDesc('size');
//= SELECT * FROM animals ORDER BY size DESC;
Animal.orderAsc('bones');
//= SELECT * FROM animals ORDER BY bones ASC;
int — A number to limit the results by.int — A number to offset the results by.object array query — An object of the data, with correctly named columns, to be inserted into the table. With Postgres & SQLite it also can be an array of objects or a subquery.For Postgres, #insert() also returns the ID attribute.
Animal.insert({ name: 'Siberian Tiger', species: 'P. tigris altaica' });
//= INSERT INTO animals (name,species) VALUES ('Siberian Tiger','P. tigris altaica') RETURNING id;
Animal.insert([
{ name: 'Puma', species: 'Puma concolor' },
{ name: 'Jackalope' }
]);
//= INSERT INTO animals (name,species) VALUES ('Puma','Puma concolor'), ('Jackalope',NULL);
Person.create(Client.select('name').where({ type: 'new' }));
//= INSERT INTO people (SELECT name FROM clients WHERE type = 'new');
int int[] — The optional id(s) of the items to update (if omitted, a where() method is required).object — An object of the data, with correctly named columns, to be updated.Book.update(55688, { title: 'The Great Gatsby' });
//= UPDATE books SET (title) = ('The Great Gatsby') WHERE id IN (55688);
Book.update({ publisher: 'Brown Little' }).where({ publisher: 'Brown' });
//= UPDATE books SET (publisher) = ('Brown Little') WHERE publisher = 'Brown';
int int[] — The optional id(s) of the items to update (if omitted, a where() method is required before remove is called).Person.remove(345267);
Person.remove([5610, 5615]);
Person.where({ name: 'Mark' }).remove();
//= DELETE FROM people WHERE name = 'Mark';
Ends the Postgres pool connection. Connection will end automatically after 10 seconds if no queries are running. (Otherwise a new connection begins when a query is run.)
### Query: returning(fields, [callback])string string[] — the name of the field to return, or an array of fields.Adding the #returning() method to a query chain (either insert or update)
### Data type: ArrayValues provided as an Array will be sent to the server as a Postgres Array data type (see more in the Postgres docs). So [1, 2, 3, 4] will be stored in Postgres as '{1, 2, 3, 4}'.
Values provided as a JSON will be sent to the server as an hstore data type, a storage of key/values (see more in the Postgres docs). So { one: 1, two: 'three' } will be stored in Postgres as 'one => 1, two => "three"'.
Enclose the value in two nested arrays to avoid any value escaping. So [['\n']] will result in a String of '\n' and not '\\n' as usual.
FAQs
An activerecord-inspired ORM for Node.js
The npm package grand-central-records receives a total of 1 weekly downloads. As such, grand-central-records popularity was classified as not popular.
We found that grand-central-records 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.
Security News
TC39 met in Seattle and advanced 9 JavaScript proposals, including three to Stage 4, introducing new features and enhancements for a future ECMAScript release.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.