ngx-warehouse
TypeScript icon, indicating that this package has built-in type declarations

1.0.2 • Public • Published

ngx-warehouse

Build Status npm version devDependency Status GitHub issues GitHub stars GitHub license

https://phillipcurl.github.io/ngx-warehouse

Table of contents

About

An offline storage solution for Angular apps built on top of LocalForage.

Installation

Install via npm:

$ npm install --save ngx-warehouse

or Yarn:

$ yarn add ngx-warehouse

Then include in your apps module:

import { Component, NgModule } from '@angular/core';
import { NgxWarehouseModule } from 'ngx-warehouse';
 
@NgModule({
  imports: [
    NgxWarehouseModule
  ]
})
export class MyModule {}

Configuration

You can also configure the NgxWarehouseModule, though it does come with default options to allow you to get up and running quickly.

import { NgxWarehouseModule, WarehouseConfig, DRIVER_TYPE } from 'ngx-warehouse';
 
const config: WarehouseConfig = {
  driver: DRIVER_TYPE.DEFAULT,
  name: 'Your App',
  version: 1.0,
  storeName: 'key_value_pairs', // Should be alphanumeric, with underscores.
  description: 'A description of your app'
};
 
@NgModule({
  declarations: [...],
  imports: [
    ...
    NgxWarehouseModule.configureWarehouse(config),
    ...
  ],
  bootstrap: [...]
})

The following DRIVER_TYPE's are available:

  • DEFAULT - The warehouse will first try to connect to IndexedDB, then WebSQL, and finally LocalStorage if the first two fail.
  • INDEXEDDB - Force the connection to IndexedDB.
  • WEBSQL - Force the connection to WebSQL.
  • LOCALSTORAGE - Force the connection to LocalStorage.

Usage

Now you're ready to use ngx-warehouse in your app:

import { Warehouse } from 'ngx-warehouse';
 
@Component({
  ...
})
export class MyComponent implements OnInit {
 
  constructor(public warehouse: Warehouse) { }
 
  ngOnInit() {
    this.warehouse.get('key').subscribe(
      data => console.log(data),
      error => console.log(error)
    );
  }
 
}

You may also find it useful to view the demo source.

API

Warehouse.set(key: string, value: any): Observable < any >

Saves an item to the current offline data store. The following data types are valid:

  • Array
  • ArrayBuffer
  • Blob
  • Float32Array
  • Float64Array
  • Int8Array
  • Int16Array
  • Int32Array
  • Number
  • Object
  • Uint8Array
  • Uint8ClampedArray
  • Uint16Array
  • Uint32Array
  • String
Warehouse.set('key', value).subscribe(
  (item) => {
    // do something with newly saved item
  },
  (error) => {
    // handle the error
  }
);

Warehouse.get(key: string): Observable < any >

Gets an item from the storage library and supplies the result to a callback. If the key does not exist, getItem() will return null.

Even if undefined is saved, null will be returned by getItem(). This is due to a limitation in localStorage, and for compatibility reasons localForage cannot store the value undefined.

Warehouse.get('key').subscribe(
  (data) => {
    // do something with the data
  },
  (error) => {
    // handle the error
  }
);

Warehouse.remove(key: string): Observable < any >

Removes the value of a key from the offline store.

Warehouse.remove('key').subscribe(
  (success) => {
    // do something on success
  },
  (error) => {
    // handle the error
  }
);

Warehouse.destroy(): Observable < any >

USE WITH CAUTION: Removes every key from the database, returning it to a blank slate.

Warehouse.destroy().subscribe(
  (success) => {
    // do something on success
  },
  (error) => {
    // handle the error
  }
);

Warehouse.count(): Observable < number >

Gets the number of keys in the offline store (i.e. its “length”).

Warehouse.count().subscribe(
  (success) => {
    // do something on success
  },
  (error) => {
    // handle the error
  }
);

Warehouse.key(): Observable < string >

Get the name of a key based on its ID.

This method is inherited from the localStorage API, but is acknowledged to be kinda weird.

Warehouse.count().subscribe(
  (success) => {
    // do something on success
  },
  (error) => {
    // handle the error
  }
);

Warehouse.keys(): Observable < string[] >

Get the list of all keys in the datastore.

Warehouse.count().subscribe(
  (success) => {
    // do something on success
  },
  (error) => {
    // handle the error
  }
);

Usage without a module bundler

<script src="node_modules/dist/umd/ngx-warehouse/ngx-warehouse.js"></script>
<script>
    // everything is exported ngxWarehouse namespace
</script>

Documentation

All documentation is auto-generated from the source via typedoc and can be viewed here: https://phillipcurl.github.io/ngx-warehouse/docs/

Development

Prepare your environment

  • Install Node.js and NPM (should come with)
  • Install local dev dependencies: npm install while current directory is this repo

Development server

Run npm start to start a development server on port 8000 with auto reload + tests.

Testing

Run npm test to run tests once or npm run test:watch to continually run tests.

Release

  • Bump the version in package.json (once the module hits 1.0 this will become automatic)
npm run release

License

MIT

Package Sidebar

Install

npm i ngx-warehouse

Weekly Downloads

1

Version

1.0.2

License

MIT

Last publish

Collaborators

  • philcurl