1.21.17 • Published 12 months ago

@onehat/data v1.21.17

Weekly downloads
237
License
MIT
Repository
github
Last release
12 months ago

Overview

@onehat/data A robust ORM for Javascript. Can CRUD, search, sort, filter, paginate your data. Integrates with many front- and back-end storage mediums.

  • Repositories. A Repository stores many Entities in a storage medium. Corresponds to a database table. Repositories can sort, search/filter, and add/edit/delete their constituent Entities.
  • Storage Mediums. Repositories are specialized to store their data in a single type of storage medium. Available types of Repositories include: Memory, Ajax, Rest, LocalStorage (Browser), SessionStorage (Browser), IndexedDB (Browser), AsyncStorage (React Native/Expo), SecureStore (React Native/Expo). One special type of Repository—LocalFromRemote—combines two different Repository types (one local and one remote) into a single Repository, thereby allowing autosyncing between the local and remote repositories, enabling true offline-first capability.
  • Entities. An Entity is a single record of data, organized into properties. Corresponds to a database row. Entity data can be accessed directly (entity.username), via specific properties and their formatted values (entity.properties.username.displayValue), or by obtaining a JS object of the whole Entity (entity.getDisplayValues(), or entity.getSubmitValues()).
  • Properties. A Property is a single unit of data. Corresponds to a database field. Properties are differentiated into different Property types (e.g. Integer, String, Boolean, etc), and thereby allow for easy formatting of "display" or "submit" values. For example, a date might be set to display as "Wed, Feb 5, 2020" but submit as "2020-02-05".
  • Schemas. A Schema defines the configuration of a Repository. Corresponds roughly to the database table schema. The Schema defines the name and type of Repository, the Properties that exist, and which are "id" and "display" Properties.

Install

npm i @onehat/data

Usage

Comprehensive unit tests can be found in ./cypress/integration. These are an excellent source of code examples. Comprehensive API documentation can be found in ./docs.

1. Define a Schema

For every type of Entity you will use (e.g. Users or Animals or Invoices), define a Schema. A Schema determines the various Properties that each Entity will have, as well as the medium where the Entities will be stored.

const Users = {
	name: 'Users',
	model: {
		idProperty: 'id',
		displayProperty: 'username',
		properties: [
			{ name: 'id', type: 'int', },
			{ name: 'username', type: 'string', }, // explicitly set property type
			{ name: 'password', }, // type: 'string' is assumed, if not explicitly set
			{ name: 'first_name', },
			{ name: 'last_name', },
			{ name: 'email', allowNull: false, }, // make it a required field
			{ name: 'last_login', type: 'datetime', defaultValue: 'now', }, // give it a default value.
		],
		sorters: [
			{
				name: 'last_name',
				direction: 'ASC',
			},
			{
				name: 'first_name',
				direction: 'ASC',
			},
		],
	},
	repository: 'memory', // Repository type. Can be string name or config object
};
export default Users;

Every Property must have a unique name. All other attributes are optional. Common Property attributes include:

  • name - The name of the Property
  • type - The type of the Property (e.g. 'string', 'bool', 'int', etc)
  • allowNull - Is this Property required to have a value?
  • defaultValue - Default value for this Property if none is supplied
  • isSortable - Whether this Property type is sortable

Other Property attributes exist and can be found in the API.

2. Create a Repository

The easiest way to create one or more Repositories is to use the global oneHatData singleton object. Each schema will have a bound repository of the same name (e.g. "Users", or "Groups").

import oneHatData from '@onehat/data';
import Groups from './Groups';
import Users from './Users';

oneHatData
	.createSchemas([
		Groups,
		Users,
	])
	.createBoundRepositories()
	.then(() => {
		setIsReady(true);
		
		const UsersRepository = oneHatData.getRepository('Users');

		// Do something with your data

	});

3. Add / Edit / Delete an Entity

Once you have a Repository initialized, you can start adding data to it. Data is manipulated asynchronously, so you may optionally wait for it to complete.

const UsersRepository = oneHatData.getRepository('Users');

// 1. Add an Entity
const userEntity = await UsersRepository.add({
	username: 'ajones',
	password: '12345',
	first_name: 'Alice',
	last_name: 'Jones',
	email: 'alice@example.com',
});


// 2. Edit an Entity
// Use assignment to change the value of a particular Property.
userEntity.password = 'mypass';

// Or you can be more verbose about it
userEntity.getProperty('password').setValue('mypass');


// 3. Delete an Entity
userEntity.delete();

// Or delete it from the Repository
await UsersRepository.delete(userEntity);

4. Filter and Sort the Entities in a Repository

There are lots of filtering and sorting methods available on Repositories.

// Add a single filter
UsersRepository.filter('first_name', 'Alice');
const foundEntities = UsersRepository.entities;

// Or search by an id or function
const myEntity = UsersRepository.getById(1);
const results = UsersRepository.getBy((entity) => {
	return entity.id > 2;
});

// Sort the entities by a particular Property
UsersRepository.sort('last_name', 'DESC');
const sortedEntities = UsersRepository.entities;

5. Listen for events and respond to them

Repositories, Entities, and Properties emit many different kinds of events.

// The 'change' event, emitted from an Entity, is relayed through the Repository and becomes 'entity_change'
UsersRepository.on('entity_change', (entity) => {
	console.log('changed entity');
});
userEntity.first_name = 'Joe';
// prints 'changed entity' to console


// The 'changeData' event is fired from the Repository after multiple Entities are loaded at once
UsersRepository.on('changeData', (entities) => {
	console.log('entities changed');
});
UsersRepository.load([
	{ email: 'alice@example.com' },
	{ email: 'bob@example.com' },
	{ email: 'charlie@example.com' },
]);
// prints 'entities changed' to console
1.21.17

12 months ago

1.21.15

12 months ago

1.21.16

12 months ago

1.21.14

12 months ago

1.21.13

12 months ago

1.21.12

1 year ago

1.21.11

1 year ago

1.21.10

1 year ago

1.21.0

1 year ago

1.21.1

1 year ago

1.21.5

1 year ago

1.21.2

1 year ago

1.21.3

1 year ago

1.21.8

1 year ago

1.21.9

1 year ago

1.21.6

1 year ago

1.21.7

1 year ago

1.20.9

1 year ago

1.20.7

1 year ago

1.20.8

1 year ago

1.20.5

1 year ago

1.20.6

1 year ago

1.20.4

1 year ago

1.20.3

1 year ago

1.20.1

2 years ago

1.20.2

2 years ago

1.20.0

2 years ago

1.19.41

2 years ago

1.19.40

2 years ago

1.19.39

2 years ago

1.19.38

2 years ago

1.19.36

2 years ago

1.19.37

2 years ago

1.19.35

2 years ago

1.19.30

2 years ago

1.19.31

2 years ago

1.19.32

2 years ago

1.19.33

2 years ago

1.19.28

2 years ago

1.19.29

2 years ago

1.19.27

2 years ago

1.19.26

2 years ago

1.19.25

2 years ago

1.19.24

2 years ago

1.18.9

2 years ago

1.18.8

2 years ago

1.18.7

2 years ago

1.19.0

2 years ago

1.19.4

2 years ago

1.19.3

2 years ago

1.19.2

2 years ago

1.19.1

2 years ago

1.19.8

2 years ago

1.19.7

2 years ago

1.19.6

2 years ago

1.19.5

2 years ago

1.19.9

2 years ago

1.19.12

2 years ago

1.19.13

2 years ago

1.19.10

2 years ago

1.19.11

2 years ago

1.19.16

2 years ago

1.19.17

2 years ago

1.19.14

2 years ago

1.19.15

2 years ago

1.19.18

2 years ago

1.19.19

2 years ago

1.19.20

2 years ago

1.19.21

2 years ago

1.19.22

2 years ago

1.18.12

2 years ago

1.18.11

2 years ago

1.18.10

2 years ago

1.18.13

2 years ago

1.18.1

2 years ago

1.18.0

2 years ago

1.18.4

2 years ago

1.18.3

2 years ago

1.18.2

2 years ago

1.16.10

2 years ago

1.16.9

2 years ago

1.17.2

2 years ago

1.17.0

2 years ago

1.17.5

2 years ago

1.17.3

2 years ago

1.14.1

3 years ago

1.15.0

3 years ago

1.15.4

3 years ago

1.15.3

3 years ago

1.15.2

3 years ago

1.15.1

3 years ago

1.15.7

2 years ago

1.15.6

2 years ago

1.15.5

3 years ago

1.16.3

2 years ago

1.16.2

2 years ago

1.16.1

2 years ago

1.16.0

2 years ago

1.16.7

2 years ago

1.16.6

2 years ago

1.16.8

2 years ago

1.14.0

3 years ago

1.12.0

3 years ago

1.13.2

3 years ago

1.13.1

3 years ago

1.13.0

3 years ago

1.13.6

3 years ago

1.13.5

3 years ago

1.13.4

3 years ago

1.13.3

3 years ago

1.10.5

3 years ago

1.10.4

3 years ago

1.10.3

3 years ago

1.10.2

3 years ago

1.11.4

3 years ago

1.11.3

3 years ago

1.11.2

3 years ago

1.11.1

3 years ago

1.11.6

3 years ago

1.11.5

3 years ago

1.9.1

3 years ago

1.9.0

3 years ago

1.10.1

3 years ago

1.10.0

3 years ago

1.8.26

3 years ago

1.8.27

3 years ago

1.8.28

3 years ago

1.8.29

3 years ago

1.8.30

3 years ago

1.8.31

3 years ago

1.8.32

3 years ago

1.8.33

3 years ago

1.8.34

3 years ago

1.8.35

3 years ago

1.9.3

3 years ago

1.9.2

3 years ago

1.11.0

3 years ago

1.8.20

3 years ago

1.8.21

3 years ago

1.8.22

3 years ago

1.8.23

3 years ago

1.8.24

3 years ago

1.8.25

3 years ago

1.8.19

3 years ago

1.8.13

3 years ago

1.8.14

3 years ago

1.8.15

3 years ago

1.8.16

3 years ago

1.8.17

3 years ago

1.8.18

3 years ago

1.8.9

3 years ago

1.8.10

3 years ago

1.8.8

3 years ago

1.8.11

3 years ago

1.8.7

3 years ago

1.8.12

3 years ago

1.7.16

3 years ago

1.8.2

3 years ago

1.8.1

3 years ago

1.8.0

3 years ago

1.8.6

3 years ago

1.8.5

3 years ago

1.8.4

3 years ago

1.8.3

3 years ago

1.7.15

3 years ago

1.6.4

4 years ago

1.6.3

4 years ago

1.6.1

4 years ago

1.6.0

4 years ago

1.7.10

4 years ago

1.7.11

4 years ago

1.7.12

4 years ago

1.7.14

4 years ago

1.7.9

4 years ago

1.7.8

4 years ago

1.7.7

4 years ago

1.7.6

4 years ago

1.7.5

4 years ago

1.7.4

4 years ago

1.5.2

4 years ago

1.5.1

4 years ago

1.5.0

4 years ago

1.6.9

4 years ago

1.6.8

4 years ago

1.6.7

4 years ago

1.6.6

4 years ago

1.4.11

4 years ago

1.6.5

4 years ago

1.4.10

4 years ago

1.4.13

4 years ago

1.4.12

4 years ago

1.4.14

4 years ago

1.6.11

4 years ago

1.6.10

4 years ago

1.6.13

4 years ago

1.6.12

4 years ago

1.7.3

4 years ago

1.7.2

4 years ago

1.7.1

4 years ago

1.7.0

4 years ago

1.4.9

4 years ago

1.4.8

4 years ago

1.4.7

4 years ago

1.4.6

4 years ago

1.4.5

4 years ago

1.4.4

4 years ago

1.4.3

4 years ago

1.4.2

4 years ago

1.4.1

4 years ago

1.4.0

4 years ago

1.3.3

4 years ago

1.3.2

4 years ago

1.3.1

4 years ago

1.3.0

4 years ago

1.2.6

4 years ago

1.2.5

4 years ago

1.2.4

4 years ago

1.2.3

4 years ago

1.2.2

4 years ago

1.2.1

4 years ago

1.2.0

4 years ago

1.1.15

5 years ago

1.1.14

5 years ago

1.1.13

5 years ago

1.1.9

5 years ago

1.1.8

5 years ago

1.1.12

5 years ago

1.1.11

5 years ago

1.1.10

5 years ago

1.1.7

5 years ago

1.1.6

5 years ago

1.1.5

5 years ago

1.1.4

5 years ago

1.1.3

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.1.2

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

0.13.6

5 years ago

0.13.5

5 years ago

0.13.4

5 years ago

0.13.3

5 years ago

0.13.2

5 years ago

0.13.0

5 years ago

0.13.1

5 years ago

0.12.5

5 years ago

0.12.4

5 years ago

0.12.3

5 years ago

0.12.2

5 years ago

0.12.1

5 years ago

0.12.0

5 years ago

0.11.9

5 years ago

0.11.8

5 years ago

0.11.7

5 years ago

0.11.5

5 years ago

0.11.6

5 years ago

0.11.2

5 years ago

0.11.3

5 years ago

0.11.4

5 years ago

0.11.1

5 years ago

0.11.0

5 years ago

0.10.3

5 years ago

0.10.2

5 years ago

0.10.1

5 years ago

0.10.0

5 years ago

0.9.2

5 years ago

0.9.1

5 years ago

0.9.0

5 years ago

0.8.13

5 years ago

0.8.12

5 years ago

0.8.11

5 years ago

0.8.10

5 years ago

0.8.9

5 years ago

0.8.5

5 years ago

0.8.7

5 years ago

0.8.6

5 years ago

0.8.4

5 years ago

0.8.2

5 years ago

0.8.1

5 years ago

0.8.0

6 years ago