global-store 1.0.0-beta.2 → 1.0.0-beta.20

package/README.md

@@ -1,40 +1,35 @@
 # global-store
 
 [![NPM version][npm-image]][npm-url]
-[![NPM beta version][npm-beta-image]][npm-url]
 [![NPM downloads][downloads-image]][downloads-url]
 ![badge-size-es5-url]
-![badge-size-esnext-url]
 
-[![Circle CI][circleci-image]][circleci-url]
-[![Travis CI][travis-image]][travis-url]
+[![GitHub NodeJS][github-nodejs]][github-action-url]
 [![Codecov][codecov-image]][codecov-url]
-[![Coveralls Status][coveralls-image]][coveralls-url]
 
-[![Greenkeeper][greenkeeper-image]][greenkeeper-url]
 [![Visual Studio Code][vscode-image]][vscode-url]
-[![Wallaby.js][wallaby-image]][wallaby-url]
 
-[`global-store`](https://github.com/unional/global-store) provides version stable stores for library.
+[global-store] provides version stable stores for libraries.
 
 Once this library reaches `1.0`, it will forever be backward compatible.
-Meaning there will never be a breaking change and `2.0` version of this library.
+Meaning there will never be a breaking change or `2.0` version of this library.
 
 PLEASE NOTE: This document describes the new `1.0.0-beta` version (finally!! :tada:).
 
 For the current stable version, please check out [here](https://github.com/unional/global-store/blob/v0.8.2/README.md).
 
-## Who need this
+## Who needs this
 
-- library can be used by other libraries, and
-- library with state, and/or
-- library wants to protect its state from modification.
+- A library used by other libraries, and
+- A library with state, and/or
+- A library wants to protect its state from modification.
 
 ## Why do you need this
 
-If you use a file level variable to store some states,
+If you use a file-level variable to store some states,
 and your library can be used by other libraries,
-the state it stores could scatter around the memory and you will get inconsistent result.
+the state it stores could scatter around the memory,
+and you will get inconsistent results.
 
 For example, you have this:
 
@@ -50,7 +45,7 @@ When your library is used by other libraries,
 they may use different versions.
 For example:
 
-```
+```sh
 app
 - some-library@1.5
   - your-library@1.0
@@ -60,183 +55,193 @@ app
 Since the versions are not compatible,
 both versions of your library are loaded thus two instances of the `registry` variable exist and contain different values.
 
-Solution to this problem is to use some form of global storage such as `process.env` in NodeJS,
-and `localStorage` or global variable in browser.
+The solution to this problem is to use some form of global storage such as `global` in NodeJS,
+or global variable in the browser.
 
 The problem is that these mechanisms are shared by everything else in the application,
 completely exposed to everyone,
-and there is no mechanism to consolidate your state when they are populated by each version of your library being loaded.
+and there is no mechanism to consolidate or protect your state when they are populated by each version of your library being loaded.
+
+These are the problems addressed by [global-store].
 
-These are the problems addressed by [`global-store`](https://github.com/unional/global-store).
+## Installation
+
+```sh
+npm install global-store
+yarn add global-store
+```
 
 ## API
 
 ### createStore()
 
-`createStore()` creates a version stable store.
+Type: `<T>(options: StoreOptions<T>) => Store<T>`
+
+Creates a store of type `T`.
+
+`T` is inferred by [`initializer`](#StoreOptionsInitializer).
 
 ```ts
 import { createStore } from 'global-store'
 
-const store = createStore(
-  'your-module',
-  'unique-string',
-  previous => ({ ...previous, prop1: false, prop2: [] as string[] })
-)
+const store = createStore({
+  moduleName: 'your-module',
+  key: 'some-unique-string',
+  version: '1.0.0',
+  initializer: (current, versions) => ({
+    prop1: false,
+    prop2: [] as string[],
+    ...current
+  })
+})
 
-console.log(store.get().prop1) // false
+console.log(store.value.prop1) // false
 
-store.get().prop1 = true
-store.get().prop2.push('a')
-console.log(store.get()) // { prop1: true, prop2: ['a'] }
+store.value.prop1 = true
+store.value.prop2.push('a')
+console.log(store.value) // { prop1: true, prop2: ['a'] }
 ```
 
-#### createStore(moduleName, key, initializer)
-- `moduleName: string`: Name of your module. This is typically your npm package name.
-- `key: string | symbol`: The `key` should be unique for each store you create.
-  You can use some random string such as UUID.
-  You can also use `symbol`, but not that you need to use the `Symbol.for('key')` variant as `Symbol()` does not work for this purpose.
-  Together with `moduleName`, `key` + `moduleName` forms an unique id to the store.
-- `initializer: (previous) => initValue`: initializer to initialize the store.
-  Since there may be multiple copies of your library loaded,
-  multiple calls to [`createStore()`](#createStore()) may occur.
-  For the first call, the `previous` argument will be an empty object.
-  For subsequence calls, it will be the value returned by the last call.
-  Since there is no way to control the load order,
-  [`createStore()`](#createStore()) can be called by a newer version of your libary before an older version.
-  That means your `initializer` needs to be future proof.
-  To do that, you should carry over what the previous call have created,
-  and fill in the pieces your specific version needs.
-  In addition, you can use a property such as `revisions` or `versions` to help this process.
-
-#### Store#get()
-
-Gets the store value.
-Also use this to update the store.
+#### StoreOptions#moduleName
 
-```ts
-import { createStore } from 'global-store'
+Type: `string`
 
-const store = createStore(
-  'your-module',
-  'general:300c47d7-b3a8-43ee-9dea-1e05a7b34240',
-  p => ({ ...p, a: 1 })
-)
+Name of your module.
 
-store.get().a = 2
+This is typically your NPM package name.
+This will be shown if something goes wrong.
 
-console.log(store.get().a) // 2
-```
+#### StoreOptions#key
 
-#### Store#reset()
+Type: optional `string`
 
-Reset the store to its initial value.
+A specific key for each store in your module.
+
+You can create multiple stores in your module for different purposes.
+The key for each store needs to be unique.
+And the key has to remain the same across versions.
+
+For example, you can use a format like this to make it unique: `<some-purpose>:<UUID>`
+
+e.g. `config:d15427a4-75cf-4999-9065-1dc325839a59`
+
+`key` + `moduleName` forms a unique ID to the store.
+
+`key` will not be shown if something goes wrong.
+
+If `key` is not specified, it defaults to the string `default`.
 
-This is used mostly in your test, so that the tests would not interferred each other.
+#### StoreOptions#version
 
-### createReadonlyStore()
+Type: `StoreVersion = string | number`
 
-`createReadonlyStore()` creates a version stable store that prevents modification.
+The version of the store.
 
-Its signature is the same as [`createStore()`](#createStore()).
-The returned `ReadonlyStore` has the following additional features:
+This is used during initialization to determine should the [`StoreOptions#initializer`](#StoreOptionsinitializer) be called (and in what order for [`createAsyncStore()`](#createAsyncStore)).
 
-#### ReadonlyStore#get()
+It will be added to the `processedVersions` argument of the [`StoreOptions#initializer()`](#StoreOptionsinitializer) after it is being called.
 
-When the store is created,
-calling `get()` would result in error if `lock()` is not called.
-This avoids the store to be used accidentially without protection.
+When specified as a string (recommended),
+it must be in this format: `major.minor.patch`.
 
-#### Readonly#lock()
+When there is a mix of string and numeric versions across different versions of your library,
+the numeric value is compared to the patch number of the string version.
 
-Lock the store, making it read only.
+#### StoreOptions#initializer()
 
-Then the store is locked, the following happens:
+Type: `<T extends StoreValue>(current: StoreValue, processedVersions: StoreVersion[]) => T`
 
-- the value is frozen, making each property read only.
-- if the property is an array, it is also frozen,
-  making it unable to add or remove entry.
-- [`get()`](#ReadonlyStore#get()) is open to be used.
-- [`reset()`](#ReadonlyStore#reset()) results in error.
-- [`getWritable()`](#ReadonlyStore#getWritable()) results in error.
-- [`openForTesting()`](#ReadonlyStore#openForTesting()) results in error.
+The function to initialize the store.
 
-`lock()` takes an optional `finalizer` argument.
-It can contains properties matching the property names of the store,
-where each one is a transform function for that property.
+Since there may be multiple copies of your library loaded,
+multiple calls to the store creation function (e.g. [`createStore()`](#createStore)) may occur.
+For the first call, the `current` argument will be an empty object.
+For subsequence calls, it will be the value returned by the last call.
 
-It allows you to process the store before it is locked.
+The `processedVersions` contains all the versions the have been processed so far.
+You can use it to help determine what do you need to do.
 
-The typical use cases are to validate, clean up, transform, and freeze the values.
+For [`createAsyncStore`](#createAsyncStore),
+the `initializer` function will be called in the order of `version`.
+
+For [`createStore`](#createStore),
+since there is no way to control the load order,
+they can be called by a newer version of your library before an older version.
+This means your `initializer` needs to be future-proof.
+
+To do that, you should fill in the pieces your specific version needs,
+and carry over whatever is currently available.
+
+This is only a general guideline,
+the actual implementation will depend on how you use your store.
+
+#### StoreValue
+
+Type: `Record<string | symbol, any>`
+
+The type of value stored in the stores.
+
+Note that the key must be a string or `Symbol.for()` because `Symbol()` cannot be shared across versions.
+
+#### Store#value
+
+Access to the value in the store.
 
 ```ts
-import { createReadonlyStore } from 'global-store'
-
-const store = createStore(
-  'your-module',
-  'general:ea305f50-c48c-4d18-97ef-4c8e8f130446',
-  p => ({ ...p, a: 1, b: [], c: {} })
-)
-
-store.lock({
-  b: values => values.map(v => Object.freeze(v)),
-  c: value => Object.freeze(value),
-  prev: value => undefined // make the older version property disappear.
-})
+import { createStore } from 'global-store'
+
+const store = createStore({ ..., initializer: () => ({ x: 1 })}
+
+console.info(store.value.x) // 1
+store.value.x = 2
 ```
 
-#### ReadonlyStore#getWritable()
+#### Store#reset()
 
-Before the store is locked,
-you need a mechanism to access the store and configure it.
-`getWritable()` by pass the check and allow you to do that.
+Reset the store to its initial value.
 
-Once the store is locked, calling `getWritable()` results in error.
+This is mostly used in tests so that the tests would not interfere with each other.
 
-#### ReadonlyStore#openForTesting()
+### createAsyncStore()
 
-During testing,
-you need a mechanism to allow the [`get()`](#ReadonlyStore#get()) calls to go through without locking the store.
-`openForTesting()` tells the store to turn off all checks so it can be used during test.
+A `async` variant of [`createStore()`](#createStore).
+It will return a promise,
+which will resolve when the [`initializeAsyncStore()`](#initializeAsyncStore) is called.
 
-Due to its power, you should not have any code calling this method except in your test code.
+One benefit of using this over [`createStore()`](#createStore) is that the initializers will be called in the order of `version`.
 
-## Installation
+This makes initialization much easier to handle.
 
-```sh
-npm install global-store
-yarn add global-store
-```
+### initializeAsyncStore()
+
+Calling [`initializeAsyncStore()`](#initializeAsyncStore) will start the initialization process of [`createAsyncStore()`](#createAsyncStore).
+
+It takes two arguments:
+
+- `moduleName: string`: Name of your module.
+- `key: string`: Optional. Key of the specific store to initialize.
+  If omitted, all stores in the module will be initialized.
 
 ## Bundling
 
-If your library will be a standalone bundle, make sure to exclude [`global-store`](https://github.com/unional/global-store).
-If not, there will be multiple copies of [`global-store`](https://github.com/unional/global-store) loaded and will completely defeat the purpose.
+If your library will be a standalone bundle, make sure to exclude [global-store].
 
-You also should mark [`global-store`](https://github.com/unional/global-store) as a peer dependency and tell people who use your library to include [`global-store`](https://github.com/unional/global-store) as their dependency.
+If not, there will be multiple copies of [global-store] loaded and will completely defeat the purpose.
 
-Any application that eventually uses your library should do the same, install [`global-store`](https://github.com/unional/global-store) as their own dependency.
+Except the consuming application, which will declare [global-store] as a regular dependency,
+all libraries should declare [global-store] as a peer dependency.
 
-[badge-size-es5-url]: http://img.badgesize.io/unional/global-store/master/dist/global-store.es5.js.svg?label=es5_size
-[badge-size-esnext-url]: http://img.badgesize.io/unional/global-store/master/dist/global-store.es.js.svg?label=esnext_size
-[circleci-image]: https://circleci.com/gh/unional/global-store/tree/master.svg?style=shield
-[circleci-url]: https://circleci.com/gh/unional/global-store/tree/master
+[badge-size-es5-url]: http://img.badgesize.io/unional/global-store/master/dist/global-store.es5.js.svg?label=es5_size&compression=gzip
 [codecov-image]: https://codecov.io/gh/unional/global-store/branch/master/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/unional/global-store
-[coveralls-image]: https://coveralls.io/repos/github/unional/global-store/badge.svg
-[coveralls-url]: https://coveralls.io/github/unional/global-store
 [downloads-image]: https://img.shields.io/npm/dm/global-store.svg?style=flat
 [downloads-url]: https://npmjs.org/package/global-store
-[greenkeeper-image]: https://badges.greenkeeper.io/unional/global-store.svg
-[greenkeeper-url]: https://greenkeeper.io/
-[npm-beta-image]: https://img.shields.io/npm/v/global-store/beta.svg?style=flat
+[github-nodejs]: https://github.com/unional/global-store/workflows/release/badge.svg
+[github-action-url]: https://github.com/unional/global-store/actions
+[global-store]: https://github.com/unional/global-store
 [npm-image]: https://img.shields.io/npm/v/global-store.svg?style=flat
 [npm-url]: https://npmjs.org/package/global-store
 [downloads-image]: https://img.shields.io/npm/dm/global-store.svg?style=flat
 [downloads-url]: https://npmjs.org/package/global-store
-[travis-image]: https://img.shields.io/travis/unional/global-store/master.svg?style=flat
-[travis-url]: https://travis-ci.org/unional/global-store?branch=master
 [vscode-image]: https://img.shields.io/badge/vscode-ready-green.svg
 [vscode-url]: https://code.visualstudio.com/
-[wallaby-image]: https://img.shields.io/badge/wallaby.js-configured-green.svg
-[wallaby-url]: https://wallabyjs.com

package/dist/compareVersion.d.ts

@@ -0,0 +1,7 @@
+import { StoreVersion } from './types';
+/**
+ * Compare version.
+ * Positive when processed > current
+ * Negative when processed < current
+ */
+export declare function compareVersion(processed: StoreVersion, current: StoreVersion): number;

package/dist/createAsyncStore.d.ts

@@ -0,0 +1,12 @@
+import { Store } from './createStore';
+import { StoreOptions, StoreValue } from './types';
+/**
+ * Creates a store of type T asynchronously.
+ * @see https://github.com/unional/global-store#createAsyncStore
+ */
+export declare function createAsyncStore<T extends StoreValue>({ moduleName, key, version, initializer }: StoreOptions<T>): Promise<Store<T>>;
+/**
+ * Initializes the stores for `createAsyncStore()`.
+ * @see https://github.com/unional/global-store#initializeAsyncStore
+ */
+export declare function initializeAsyncStore(moduleName: string, key?: string): void;

package/dist/createStore.d.ts

@@ -0,0 +1,28 @@
+import { StoreOptions, StoreValue } from './types';
+export declare type Store<T extends StoreValue> = {
+    /**
+     * The store value.
+     */
+    readonly value: T;
+    /**
+     * Freezes the store value.
+     * @param value Optional new store value.
+     * If supplied, this value will be freezed and used as the store value.
+     * You can use this update the store value and freeze part of it.
+     * If not supplied,
+     * the original value will be freezed and its array property will also be freezed.
+     */
+    freeze(value?: {
+        [k in keyof T]: Readonly<T[k]>;
+    }): void;
+    /**
+     * Resets the store to its initial value.
+     * You should only use this during testing.
+     */
+    reset(): void;
+};
+/**
+ * Creates a store of type T.
+ * @see https://www.npmjs.com/package/global-store
+ */
+export declare function createStore<T extends StoreValue>({ moduleName, key, version, initializer }: StoreOptions<T>): Store<T>;