sedentary

sedentary

under development

Description

An ORM which automatically syncs the DB schema on models change, no migrations between versions are required.

This package is designed to make easy the process of applying changes to the database after model definition changes, more than offer a quick and easy database access interface. Applying changes to the database after releasing a new version of the application is often a frustrating problem, usually solved with migration systems. Applying changes to the database during the development stage, often results in a complex sequence of backward and forward steps through the migrations; this process is complicated more and more especially when working in team with concurrent changes to the models (or the database schema). This package tries to solve these problems all in once.

Usage

Javascript

import { Sedentary } from "sedentary";

const db = new Sedentary("file.db");

const Items = db.model("Item", {
  num: db.INT,
  str: db.VARCHAR(30)
});

(async function () {
  await db.connect();

  const item = Items.create();

  item.num = 0;
  item.str = "0";

  await item.save();

  const records = await Items.load({});

  console.log(records); // [{ id: 1, num: 0, str: "0" }]
})();

Typescript

import { Sedentary } from "sedentary";

const db = new Sedentary("file.db");

const Items = db.model("Item", {
  num: db.INT,
  str: db.VARCHAR(30)
});
type Item = typeof Items.meta;

(async function (): Promise<void> {
  await db.connect();

  const item: Item = Items.create();

  item.num = 0;
  item.str = "0";

  await item.save();

  const records: Item[] = await Items.load({});

  console.log(records); // [{ id: 1, num: 0, str: "0" }]
})();

Table of Contents

• Installation
• Disclaimer
• Quick Start Example
  • First script example
  • First output example
  • Second script example
  • Second output example
• API
  • Class: Field
  • Class: FieldOptions
  • Class: Fields
  • Class: ModelOptions
  • Class: Model
  • Class: Sedentary
    • async sedentary.connect()
    • async sedentary.end()
    • sedentary.model(name, fields[, options])
    • new Sedentary(filename, [log])
• Compatibility
• Development
• Licence
• Bugs
• ChangeLog
• Donating

Installation

With npm:

$ npm install --save sedentary

Disclaimer

Do not use this package itself in production! This package uses a simple self made JSON-DB engine just for testing purposes.

For a real environment a DB engine dedicated extension must be used:

• MySQL: planned
• PostgreSQL: sedentary-pg
• SQLite: planned

Quick Start Example

First script example

Running following script:

First output example

we will obtain following output:

Second example script:

Changeing the script as follows and running it:

the diff is:

Second output example

we will obtain following output:

API

Class: Field

It represent a field.

Returned by sedentary.fldNumber, sedentary.fldString (and so on...) methods, should be used only for SCHEMA definition.

Class: FieldOptions

It defines the options of a filed.

Class: Fields

It defines the fields of a model.

Each key of the object represents the field name, the value represents the data type and eventualy the options.

Class: ModelOptions

Class: Model

Class: Sedentary

The base ORM class

async sedentary.connect()

Connects to the DB and syncs the schema.

Note: Must be called only once.

async sedentary.end()

Closes the connection with the DB.

Note: Must be called only once, after sedentary.connect.

sedentary.model(name, fields[, options])

• name: string   The name of the model.
• fields: Fields   The object with the fileds definitions.
• options?: ModelOptions   The options of the model.
• returns   The Model object to interact with the TABLE.

Note: Must be called before sedentary.connect.

Defines one model. Should be called once for each model/TABLE to be configured.

TypeScript: to access the type ot the records of this model one more code line is required.

const Users = db.model("User", {
  username: db.fldString(),
  level: db.fldNumber()
});
type User = typeof Users.meta; // get the record type from the model

From now on the User type can be used (for example) to give the right type to the parameter of a function which accesses a user.

function accessUser(user: User): void {
  const { username, level } = user;
  ...
}

new Sedentary(filename[, log])

• filename: string   The name of the JSON-DB file.
• log?: (message: string) => void   The log function which Sedentary will call. Default: console.log.
• returns   The Sedentary object to interact with the DB.

Compatibility

Requires:

• Node.js: v10
• TypeScript: v4.1 (or none if used in a JavaScript project).

The package is tested under all Node.js versions currently supported accordingly to Node.js Release.

To work with the package under Windows, be sure to configure bash.exe as your script-shell.

> npm config set script-shell bash.exe

Development

Since this package is the core of the ORM, probably any change on it will requires appropriate changes on the DB engine dedicated extension as well.

In order to do that, the required DB engine dedicated extensions repositories should be cheked out in the root directory of the repository of this package obtaining following directories structure:

:
|
+- sedentary
|  |
|  +- package.json
|  |
|  +- src
|  |  |
|  |  +- transaction.ts
|  :  :
|  |
|  +- sedentary-pg
|     |
|     +- package.json
|     |
|     +- src
|     |  |
:     :  :

Some make target have been added to support development of the packages together:

• make [all] - performs the basic setup (npm install, npm link, and so on ...) on all the packages
• make clean - removes TypeScript produced files
• make commit MESSAGE="" - performs git add . and git commit -m $MESSAGE in all the git repositories
• make coverage ⃰ - performs npm coverage on all the packages
• make diff - performs git diff in all the git repositories
• make outdated - runs npm outdated on all the packages
• make pull - performs git pull in all the git repositories
• make push - performs git push in all the git repositories
• make status - performs git status in all the git repositories
• make test ⃰ - performs npm test on all the packages
• make version VERSION="" - changes the versions, commits, tags and publishes everithing

Note *: Check the DB engine dedicated extensions README files for details.

Licence

MIT Licence

Bugs

Do not hesitate to report any bug or inconsistency @github.

ChangeLog

ChangeLog

Donating

If you find useful this package, please consider the opportunity to donate some satoshis to this bitcoin address: 1Md9WFAHrXTb3yPBwQWmUfv2RmzrtbHioB