@offlinely/idb
v2.1.40
Published
offline first package
Downloads
1,047
Readme
Welcome to Offlinely!
This package will help you to keep your app working offline!
Installation
yarn add @offlinely/idb
For server integration, take a look at @offlinely/server
How to use iDB
- Creating an instance of IDB
import IDB from '@offlinely/idb';
const gstDB = new IDB({
appName: 'app-ko',
token: '$2b$10$m2iQrFp0BYqtF.YFmyNTHekQV7uj', // server app token
url: 'localhost:9000', // server url
models: {
User: {
name: String,
keywords: [String],
phone: {$type: String, required: false},
role: ['ADMIN', 'SELLER', 'CUSTOMER', 'OTHER'] as const // enum like variable type
},
Car: {
owner: {$ref: 'User'},
oldOwners: {
$type: [{
user: {$ref: 'User'},
lastUse: Date
}],
required: false
},
weirdMix: [
name: String,
structure: {
keys: [{value: String, active: Boolean}],
user: [{
user: {$ref: 'User', required: false},
age: Number,
gender: ['M', 'F', 'O'] as const
}]
}
]
}
}
})
About "models"
The "models" property will generate types and will design the structure of the DB.
- No need to add
id
, it will be added later - Don't use these keywords as property in your models, unless you're using them with the intended utility:
ref
,required
andtype
.
Documentation
IDB: new IDB(IDBOptions)
new IDB({
appName: 'app-nakah',
token: 'ekQ2iHY1qtF.YFm$2b$yQrFp0BTNV0$m7uj',
url: 'localhost:9000',
models: {...}
})
IDBOptions.appName
: Name of the App this will be used for th locale and remote database name
IDBOptions.token
: Token generated on the remote backend, to access this backend (see @offlinely/server)
IDBOptions.url
: URL of the backend, dont add https
, http
or anything else, the url is just about the hostname
- Constructor : IDBOptions
| Name | Type | Required | Example | Description | |---:|---|--|---|---| | url | string | Yes | localhost:9000 | Backend socket backend URL | | appName | string | Yes | GStock | Application Name | | delay | number | No | 3000 | Milliseconds before sending data to Server | | token | string | No | - | Token sent to authenticate to a server,(Not needed for Front only app - see getTokens in @offlinely/server) | | type | DB | No | see Other DBs | Type of the offline Database used by IDB | | models | StoreModel | Yes | - | Structure of the model |
React Hooks
Typing will return the types used by your IDB if you need them.
import createHooks from '@offlinely/idb/react'
const db = new IDB({
// ...
models: {
User: { ... }
}
})
const hooks = createHooks(gstDB)
export const useGet = hooks.useGet
export const useStore = hooks.useStore
export const useWhere = hooks.useWhere
export const useList = hooks.useList
How to use React hooks
useGet(id)
| Name | Type | Required | default | Description | |---|---|--|---|---| | id | string | Yes | - | Id of the item you want |
import {userGet} from 'path/to/db'
const Component = () => {
const [jimId, setJimId] = useState("User", "iamastringid")
const user = useGet(id) // will return the user with the id
// user will change everytime jimId will change
// and when the user with the given id will be updated
}
useList(modelName, pageCount, order, 3)
| Name | Type | Required | default | Description | |---|---|--|---|---| | modelName | string | Yes | - | Key in the models | | pageCount | number | No | 0 (all) | Application Name | | order | 'ASC' or 'DESC' | No | 'DESC' | order of the list by updatedAt | | page | number | No | 1 | page of the list |
import {useList} from 'path/to/db'
const Component = () => {
const users = useList('User') // will return a list of users
// the list will be updated anytime an user will be updated
const users = useList('User', 40, 'ASC', 3)
}
Typing
const db = new IDB({
// ...
models: {
Model01: { ... },
User: { ... }
}
})
...
type Models = Typing<typeof db>
// Good typing namespaces
export type User = Models['Simple']['User']
export type Model01 = Models['Simple']['Model01']
export namespace Extended {
export type User = Models['Extended']['User']
export type Model01 = Models['Extended']['Model01']
}
Store
get(id: string): Modeled<T>
get an entry by id.User.get('2ab4a07e-88fb-4233-811e-17bac5935b62')
getAll(): Modeled<T>[]
get all entries of the StoreExample:
User.getAll()
save(entry: T): Modeled<T>
Create or Update an entry,Example:
const jacques = { username: 'jach60' } User.save(jacques)
remove(entryOrId: T | string): Modeled<T>
Remove an entry,Example:
User.remove(jacques) // or User.remove(jacques.id)
Item methods
remove(): Entry<T>
Same asStore.remove
harry.remove() // will remove this item from
update(SimplifiedItem<T>): Item<T>
Same asStore.save
- create or update an entry in the storeharry.update({ username: "harrypott", age: 23 })
StoreModel
Primitive types
new IDB({
...,
models: {
Foo: {
name: String,
age: Number,
active: Boolean,
genre: ['M', 'F', 'Other'] as const, // String but one of these values
birth: Date
}
}
})
References & Optionnal References
...
Foo: { ... },
Bar: {
foo: {$ref: 'Foo'},
optionalFoo: {$ref: 'Foo', required: false},
}
Optional properties types
...
Foo: {
age: {$type: Number, required: false},
active: {$type: Boolean, required: false},
genre: {$type: ['M', 'F', 'Other'] as const, false}
}
Arrays
...
Foo: {
nicknames: {$type: [String], required: false},
chosenNumbers: [Boolean],
likedGenres: [['M', 'F', 'Other'] as const]
}
Nested Object
...
Foo: {
like: {
bar: {$ref: 'Bar'},
reaction: ['like', 'love', 'sad', 'grrrr'] as const,
date: Date
},
comments: [{
content: String,
images: [String]
links: [{$ref: 'Link'}],
}],
likedGenres: [['M', 'F', 'Other'] as const]
}
Other DBs
For mobile use, you don't have indexedDB, for example with react-native,
Realm
We added Realm as al alternative, just install the dependancies to use it
yarn add realm react-native-get-random-values
Then write your code with specifying the DB type like this
import Realm from '@offlinely/idb/realm'
...
new IDB({
appName: 'app-nakah',
token: 'ekQ2iHY1qtF.YFm$2b$yQrFp0BTNV0$m7uj',
url: 'localhost:9000',
type: Realm,
models: {...}
})