angular-package / storage

The storage of data under allowed names.

Packages

Useful and simple to use packages based on the angular.io.

Package	Description	Status
callback	Manages the callback function.
change-detection	Improves application performance.
component-loader	Handles dynamic loading components.
core	Core features.
error	Manages an Error.
prism	Prism highlighter module.
property	Handles object properties.
storage	The storage of data under allowed names.
reactive	Automatize the process of creating some rxjs features.
testing	Support for testing other packages.
type	Common types, type guards, and type checkers.
ui	User interface.	In Progress

Click on the package name to visit its GitHub page.

angular-package/storage

The storage of data under allowed names.

---

Table of contents

• Basic concepts
• Skeleton
• Installation
• Api
• Storage
• Interface
• Type
• Experimental
• Changelog
• Git
  • Commit
  • Versioning
• License

---

Basic concepts

Checks

It's to check the provided value to be the same as expected.

Type guard (constrain)

Constrains the parameter type to not let input unexpected value in the code editor.

Guards

It's a combination of both above, constrains the type of the parameter in the code editor, and checks its provided argument.

Defines

Returns defined value from a method of an object.
Defines new value in an object and returns a defined value.

Gets

Returns a value from an object.

Sets

Adds or updates an element with a specified key and a value to an object and returns an object.

Skeleton

This package was built by the library skeleton which was generated with Angular CLI version 12.2.5.

Copy this package to the packages/storage folder of the library skeleton then run the commands below.

Code scaffolding

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

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

Build

Run ng build storage to build the package. The build artifacts will be stored in the dist/ directory.

Publishing

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

Running unit tests

Install @angular-package/testing with command:

npm i @angular-package/testing --no-save

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

Installation

Install @angular-package/storage package with command:

npm i @angular-package/storage --save

Api

import {
  // Class.
  AllowedName,
  Storage
} from '@angular-package/storage';

Storage

The storage of data under allowed names.

Instance public properties:

Storage.prototype.	Description
size: number	The size accessor property returns the number of elements in storage.

Constructor:

Constructor	Description
Storage()	Initializes an instance of Storage with optional allowed names under which values can be stored.

Instance public methods:

Storage.prototype.	Description
clear()	The clear() method removes all elements from the storage.
delete()	The delete() method removes the element from the storage using the provided name.
forEach()	The forEach() method executes a provided function once per each name/value pair in the storage, in insertion order.
get()	The get() method returns an element from the storage using the provided name.
has()	The has() method returns a boolean indicating whether an element with the provided name exists.
set()	The set() method adds or updates the value of the element under the given allowed name.
setOfType()	The setOfType() method adds or updates the element value of the type specified by the provided type under the given allowed name.

Storage instance public properties

Storage.prototype.size

The size accessor property returns the number of elements in storage.

public get size(): number {
  return super.size;
}

Storage constructor

Storage()

Initializes an instance of Storage with optional allowed names under which values can be stored.

// Syntax.
constructor(...allowNames: AllowNames[]) {
  super();
  this.#allowedName = new AllowedName(...allowNames);
}

Parameters:

Name: type	Description
...allowNames: AllowNames[]	An optional rest parameter of allowed names of string type, under which values can be stored. Only those names given by this parameter are being checked by the public isNameAllowed() of the AllowedName method and the check was not disabled by the checkNames() method.

Returns:

The return value is an instance of Storage.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Storage instance public methods

Storage.prototype.clear()

The clear() method removes all elements from the storage.

// Syntax.
public clear(): this {
  super.clear();
  return this;
}

Returns:

The return value is an instance of Storage.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Storage.prototype.delete()

The delete() method removes the element from the storage using the provided name.

// Syntax.
public delete<Name extends AllowNames>(
  name: Name,
  callback?: ResultCallback<Name>
): boolean {
  return guardString(name, callback) ? super.delete(name) : false;
}

Generic type variables:

Name	Default value	Description
Name	Captured from the name	A generic type variable Name constrained by the generic type variable AllowNames, by default of the value captured from the supplied name indicates the name under which element value is stored.

Parameters:

Name: type	Description
name: Name	The name of the generic type variable Name of the element to remove from the storage.
callback?: ResultCallback<Name>	An optional callback function of ResultCallback type to handle the check whether the provided check is a string type.

Returns:

The return value is a boolean if an element in the storage existed and has been removed or false if the element did not exist or the given name was not a string type.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Storage.prototype.forEach()

The forEach() method executes a provided function once per each name/value pair in the storage, in insertion order.

// Syntax.
public forEach(
  forEach: (
    value: any,
    name: AllowNames,
    storage: Storage<AllowNames>
  ) => void,
  callback?: ResultCallback<Function>
): this {
  guardFunction(forEach, callback) && super.forEach(forEach as any);
  return this;
}

Parameters:

Name: type	Description
forEach: Function	The callback function to execute for each entry in the storage, that takes the value and the name of each iterated element and storage being iterated.
callback?: ResultCallback<Function>	An optional callback function of ResultCallback type to handle the result of the check whether the provided forEach is the function.

Returns:

The return value is an instance of Storage.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Storage.prototype.get()

The get() method returns an element from the storage using the provided name.

// Syntax.
public get<Value = any, Name extends AllowNames = AllowNames>(
  name: Name,
  callback?: ResultCallback<Name>
): Value {
  return guardString(name, callback) && super.get(name);
}

Generic type variables:

Name	Default value	Description
Value	any	A generic type variable Value determines the type of the value parameter, by default of any via the return type.
Name	Captured from the name	A generic type variable Name constrained by the generic type variable AllowNames, by default of the value captured from the supplied name indicates the name under which element value is picked from the storage.

Parameters:

Name: type	Description
name: Name	The name of the generic type variable Name of the element to remove from the storage.
callback?: ResultCallback<Name>	An optional callback function of ResultCallback type to handle the check whether the provided name is a string type.

Returns:

The return value is an instance of Storage.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Storage.prototype.has()

The has() method returns a boolean indicating whether an element with the provided name exists.

// Syntax.
public has<Name extends AllowNames>(
  name: Name,
  callback?: ResultCallback<Name>
): boolean {
  return guardString(name, callback) && super.has(name);
}

Generic type variables:

Name	Default value	Description
Name	Captured from the name	A generic type variable Name constrained by the generic type variable AllowNames, by default of the value captured from the supplied name indicates the name under which element value is picked from the storage.

Parameters:

Name: type	Description
name: Name	The name of the generic type variable Name of the element to check for presence in the storage.
callback?: ResultCallback<Name>	An optional callback function of ResultCallback type to handle the check whether the provided name is a string type.

Returns:

The return value is a boolean indicating whether the element of the provided name exists in the storage.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Storage.prototype.set()

The set() method adds or updates the value of the element under the given allowed name.

// Syntax.
public set<Value, Name extends AllowNames>(
  name: Name,
  value: Value,
  callback?: ResultCallback<Name>
): this {
  this.#allowedName.isNameAllowed(name, callback) && super.set(name, value);
  return this;
}

Generic type variables:

Name	Default value	Description
Value	Captured from the value	A generic type variable Value determines the type of the value parameter, by default of the value captured from the supplied value.
Name	Captured from the name	A generic type variable Name constrained by the generic type variable AllowNames, by default of the value captured from the supplied name indicates the name under which element value is stored.

Parameters:

Name: type	Description
name: Name	The name of the generic type variable Name under which the element is added to the storage or updated in the storage. The value is checked against being an allowed name if the allowed names were provided.
value: Value	The value of any type to add to the storage or update in the storage under the given name.
callback?: ResultCallback<Name>	An optional callback function of ResultCallback type to handle the check whether the provided name is a string type.

Returns:

The return value is an instance of Storage.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Storage.prototype.setOfType()

The setOfType() method adds or updates the element value of the type specified by the provided type under the given allowed name.

// Syntax.
public setOfType<Value extends Type, Name extends AllowNames>(
  name: Name,
  value: Value,
  type: Types<Value>,
  callback?: ResultCallback<Name | Value>
): this {
  this._setOfType(name, value, type, callback);
  return this;
}

Generic type variables:

Name	Default value	Description
Value	Captured from the value	A generic type variable Value constrained by the generic type Type determines the type of the value parameter, by default of the value captured from the supplied value.
Name	Captured from the name	A generic type variable Name constrained by the generic type variable AllowNames, by default of the value captured from the supplied name indicates the name under which element value is stored.

Parameters:

Name: type	Description
name: Name	The name of the generic type variable Name under which the element is added to the storage or updated in the storage. The value is checked against being an allowed name if the allowed names were provided.
value: Value	The element value of the given type to add to the storage or update in the storage, under the given name.
type: Types<Value>	The type of the generic type Types indicates against which type the given value is checked.
callback?: ResultCallback<Name | Value>	An optional callback function of ResultCallback type to handle the result of the check whether the provided value is the type of the given type and the name is the allowed name under which the provided value can be stored.

Returns:

The return value is an instance of Storage.

Usage:

// Example usage.
import { Storage } from '@angular-package/storage';

Changelog

The changelog of this package is based on keep a changelog. To read it, click on the CHANGELOG.md link.

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. - keep a changelog

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)