angular-package

The angular-package supports the development process of angular-based applications in varied ways through the thoughtful, reusable, easy-to-use small pieces of code called packages.

Indexeddb

Wrapper to IndexedDB client-side storage.

Package is free to use. If you enjoy it, please consider donating via fiat, Revolut platform or cryptocurrency the @angular-package for further development. ♥

Feel free to submit a pull request. Help is always appreciated.

Table of contents

• Demonstration
• Skeleton
• Code scaffolding
• Example usage
• Documentation
  • IDBConnection Class to open connection and create object store.
  • IDBData Class with opened connection (IDBConnection), to handle transaction and store.
  • IDBQuery Query store with JSON, by method-store or store-method.
  • IDBStore Store methods with database connection (IDBData).
  • IDBConfig IDB configuration used in Angular IDBModule.
  • IDBModule Angular Module with indexeddb service.
  • IDBService Angular Service with IndexedDB class.
  • IndexedDB Store and query for IndexedDB client-side storage.
• Changelog
• Git
  • Commit
  • Versioning
• License

Demonstration

Demonstration available here as Angular 14 starter application.

Skeleton

This package was generated by the skeleton workspace with Angular CLI version 14.2.0.

Copy this package to the packages/indexeddb folder of the skeleton workspace then run the commands below.

Code scaffolding

Run ng generate component component-name --project indexeddb to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project indexeddb.

Note: Don't forget to add --project indexeddb or else it will be added to the default project in your angular.json file.

Build

Run ng build indexeddb to build the project. The build artifacts will be stored in the dist/ directory.

Publishing

After building your library with ng build indexeddb, go to the dist folder cd dist/indexeddb and run npm publish.

Running unit tests

Run ng test indexeddb to execute the unit tests via Karma.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI Overview and Command Reference page.

Example usage

Prepare configuration.

// config.ts
import { IndexedDB } from "@angular-package/indexeddb";

// Config.
export const IDB_CONFIG = IndexedDB.config({
  name: 'databasename',
  storeNames: ['storename1', 'storename2'],
  store: IndexedDB.store({
    'storename1': {
      keyPath: 'id',
      autoIncrement: false,
      index: [
        { name: "name", keyPath: "name", options: { unique: false } },
      ]
    },
    'storename2': {
      keyPath: "id",
      autoIncrement: true,
      index: [
        { name: "name", keyPath: "name", options: { unique: false } },
        { name: "position", keyPath: "position", options: { unique: false } },
        { name: "weight", keyPath: "weight", options: { unique: false } },
        { name: "symbol", keyPath: "symbol", options: { unique: false } },
      ],
    },
  }),
  version: 1
});

Use configuration and initialize database.

// example.ts
import { IndexedDB } from "@angular-package/indexeddb";
import { IDB_CONFIG } from './config';

// Initialize.
const indexeddb = new IndexedDB<
  // Create store interface.
  {
    storename1: {
      id: number,
      name: string
    },
    storename2: {
      id: number,
      name: string,
      position: number,
      weight: number,
      symbol: string
    }
  }
>(
  IDB_CONFIG.name,
  IDB_CONFIG.storeNames,
  IDB_CONFIG.store,
  IDB_CONFIG.version
);

// Add by method
indexeddb.query.method({
  'add': {
    'storename2': {
      value: {
        'id': 1,
        'name': 'name',
        'position': 1,
        'symbol': 'N',
        'weight': 100
      },
      'onsuccess': (result) => console.log(result),
      'onerror': (ev) => console.log(`error`, ev),
    }
  }
})

// Get
indexeddb.query.method({
  'get': {
    'storename2': {
      'query': 1,
      'onsuccess': (result => console.log(result)),
      'onerror': () => console.log(`error`)
    },
  }
});

// Add by store
indexeddb.query.store({
  'storename1': {
    'add': {
      'value': {
        'id': 2,
        'name': 'item'
      },
      'onsuccess': (result) => console.log(result) 
    }
  }
})

// Get
indexeddb.query.store({
  'storename1': {
    'get': {
      'query': 2,
      'onsuccess': result => console.log(result)
    }
  }
})

Documentation

The documentation is in construction and it's available at https://angular-package.gitbook.io/indexedb

IDBConnection

Class to open connection and create object store.

export class IDBConnection<
  Name extends string = string,
  StoreNames extends string | number | symbol = string,
  Version extends number = number
> { ... }

GitHub

IDBData

Class with opened connection (IDBConnection), to handle transaction and store.

export class IDBData<
  Name extends string = string,
  StoreNames extends string | number | symbol = string,
  Version extends number = number,
> { ... }

GitHub

IDBQuery

Query store with JSON, by method-store or store-method.

export class IDBQuery<
  StoreSchema extends object,
  Name extends string = string,
  StoreNames extends keyof StoreSchema = keyof StoreSchema,
  Version extends number = number
> { ... }

GitHub

IDBStore

Store methods with database connection (IDBData).

export class IDBStore<
  StoreSchema extends object,
  Name extends string = string,
  StoreNames extends keyof StoreSchema = keyof StoreSchema,
  Version extends number = number,
> implements IDBStoreInterface<StoreSchema, StoreNames> {
  ...
}

GitHub

IDBConfig

IDB configuration used in Angular IDBModule.

export class IDBConfig<
  Name extends string = string,
  StoreNames extends string | number | symbol = string,
  Version extends number = number
> {
  name?: Name;
  storeNames?: StoreNames | StoreNames[];
  store?: IDBStoreParameters<StoreNames>;
  version?: Version;
};

GitHub

IDBModule

Angular Module with indexeddb service.

@NgModule({
  declarations: [],
  imports: [
    CommonModule
  ]
})
export class IDBModule {
  static forRoot(@Optional() @Inject(IDBConfig) config?: IDBConfig): ModuleWithProviders<IDBModule> {
    return {
      ngModule: IDBModule,
      providers: [
        IDBService,
        {provide: IDBConfig, useValue: config, multi: false}
      ]
    }
  }
  static forChild(@Optional() @Inject(IDBConfig) config: IDBConfig): ModuleWithProviders<IDBModule> {
    return {
      ngModule: IDBModule,
      providers: [
        IDBService,
        {provide: IDBConfig, useValue: config, multi: false}
      ]
    };
  }
}

GitHub

IDBService

Angular Service with IndexedDB class.

@Injectable({
  providedIn: "root",
})
export class IDBService<
  StoreSchema extends object,
  Name extends string = string,
  StoreNames extends keyof StoreSchema = keyof StoreSchema,
  Version extends number = number
> {
  ...
}

GitHub

IndexedDB

Store and query for IndexedDB client-side storage.

export class IndexedDB<
  StoreSchema extends object,
  Name extends string = string,
  StoreNames extends keyof StoreSchema = keyof StoreSchema,
  Version extends number = number
> { ... }

GitHub

Changelog

To read it, click on the CHANGELOG.md link.

GIT

Commit

• AngularJS Git Commit Message Conventions
• Karma Git Commit Msg
• Conventional Commits

Versioning

Semantic Versioning 2.0.0

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

FAQ How should I deal with revisions in the 0.y.z initial development phase?

The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

License

MIT © angular-package (license)