@roots/container
Version:
Collections utility
570 lines (569 loc) • 14.9 kB
TypeScript
import type { ValueOf } from 'type-fest';
/**
* Container repository interface
*/
export interface Repository extends Record<string, any> {
}
/**
* Provides a simple chainable interface for working with collections of data
*/
export default class Container<I = any> {
/**
* Identifier
*/
ident?: string;
/**
* The container store
*/
repository: Record<string, any>;
/**
* Class constructor
*
* @param repository - Key-value data store
*/
constructor(repository?: I);
/**
* Returns the repository in its entirety as a plain JS object
*
* @example
* ```js
* container.all()
* ```
*/
all(): Record<string, any>;
/**
* Return a number indicating the length of a matched key
* in the repository.
*
* If no key is provided, returns the length of the repository.
*
* @param key - search key
* @returns count of items
*/
count(key?: string): number;
/**
* Use each value as parameters in a supplied callback
*
* @example
* ```js
* container.withEntries('key', (key, value) => doSomething)
* ```
*/
each(key: string, callFn: (key: any, value: any) => void): this;
/**
* Calls a supplied function for every repository value, passing
* the item's key and value as callback parameters.
*
* @example
* ```js
* container.withEntries('key', (key, value) => doSomething)
* ```
*/
every(fn: (key: string, value: any) => any): this;
/**
* Merges object created from an array of tuples with the repository.
*
* @example
* ```js
* container.getEntries()
* ```
*
* @example
* ```js
* container.getEntries('key')
* ```
*/
fromEntries(entries: [string, any][]): this;
/**
* Returns a value from the the repository.
*
* @remarks
* If no key is passed the container store will be returned.
*
* @example
* ```js
* container.get('container.container-item')
* ```
*
* @example
* ```js
* container.get(['container', 'container-item'])
* ```
*/
get<T = any>(key: Array<string> | string): T;
/**w
* Returns a repository key and value as a tuple
*
* @remarks
* If no key is passed the container store will be used.
*
* @example
* ```js
* container.getEntries()
* ```
*
* @example
* ```js
* container.getEntries('key')
* ```
*/
getEntries<T = any>(key?: string): [string, ValueOf<T>][];
/**
* Returns an array of values of the enumerable keys of a repository object
*
* @example
* ```js
* container.getKeys('item')
* // => returns keys of container.repository[item]
* ```
*
* @example
* ```js
* container.getKeys()
* // => returns keys of container.repository
* ```
*/
getKeys(key?: string): string[];
/**
* Get a repository item as a {@link MapConstructor}.
*
* @remarks
* If no key is passed the container store is mapped.
*
* @example
* Returns `repository.item` as a Map:
* ```js
* container.getMap('item')
* ```
*
* @example
* Returns the entire repository as a Map:
*
* ```js
* container.getMap()
* ```
*/
getMap(key?: string): Map<string, any>;
/**
* Returns an array of values of the enumerable properties of a repository object
*
* @example
* ```js
* container.getValues('container.container-item')
* ```
*
* @example
* ```js
* container.getValues()
* // => returns values from entire store
* ```
*/
getValues(key?: string): any[];
/**
* Return a boolean indicating if a given key exists.
*
* @example
* ```js
* container.has('my-key')
* // true if container.repository['my-key'] exists
* ```
*/
has(key: string): boolean;
/**
* Return a boolean indicating if the given key matches the given value.
*
* @example
* ```js
* container.is('my-key', {whatever: 'value'})
* // True if container.repository['my-key'] === {whatever: 'value'}
* ```
*/
is(key: string, value: any): boolean;
/**
* Return true if object is an array.
*
* @example
* ```js
* container.isArray('my-key')
* // True if container.repository['my-key'] is an array
* ```
*
* @param key - The key to check
* @returns True if the value is an array
*/
isArray(key: string): boolean;
/**
* Return true if object is defined.
*
* @example
* True if container has a 'my-key' entry with a definite value.
*
* ```js
* container.isDefined('my-key')
* ```
*
* @param key - The key to check.
* @returns True if the key is defined.
*/
isDefined(key: string): boolean;
/**
* Checks if value is empty. A value is considered empty unless
* it’s an arguments object, array, string, or jQuery-like
* collection with a length greater than 0 or an object with
* own enumerable properties.
*
* @example
* ```js
* container.isEmpty('my-key')
* // True if object associated with 'my-key' is empty.
* ```
*
* @param key - search key
* @returns True if object is empty.
*/
isEmpty(key?: string): boolean;
/**
* Return a boolean indicating if the given key's value is false
*
* @example
* ```js
* container.isFalse('my-key')
* // True if container.repository['my-key'] === false
* ```
*
* @param key - The key to check
* @returns True if the key's value is false
*/
isFalse(key: string): boolean;
/**
* Return true if object is a function
*
* @example
* ```js
* container.isFunction('my-key')
* // True if object associated with 'my-key' is a fn.
* ```
*
* @param key - The key to check.
* @returns True if object is a function.
*/
isFunction(key: string): boolean;
/**
* Return true if object is an instance of a class.
*
* @example
* ```js
* container.isInstanceOf('my-key', MyClass)
* // True if object associated with 'my-key' is an instance of MyClass.
* ```
*
* @param key - The key to check.
* @param instance - The class to check.
* @returns True if object is an instance of the class.
*/
isInstanceOf(key: string, instance: any): boolean;
/**
* Return true if object is an instance of any of the classes.
*
* @example
* ```js
* container.isInstanceOfAny('my-key', [MyClass, MyOtherClass])
* // True if object associated with 'my-key' is an instance of MyClass or MyOtherClass.
* ```
*
* @param key - the key to check
* @param instances - The classes to check against
* @returns
*/
isInstanceOfAny(key: string, instances: any[]): boolean;
/**
* Return true if object is not an array.
*
* @example
* ```js
* container.isNotArray('my-key')
* // True if container.repository['my-key'] is not an array
* ```
*
* @param key - The key to check
* @returns True if object is not an array
*/
isNotArray(key: string): boolean;
/**
* Checks if value is not empty. A value is considered empty unless
* it’s an arguments object, array, string, or jQuery-like
* collection with a length greater than 0 or an object with
* own enumerable properties.
*
* @example
* ```js
* container.isNotEmpty('my-key')
* // True if object associated with 'my-key' is not empty.
* ```
*
* @param key - search key
* @returns True if object is not empty.
*/
isNotEmpty(key: string): boolean;
/**
* Return true if object is not a function
*
* @example
* ```js
* container.isNotFunction('my-key')
* // True if object associated with 'my-key' is not a fn.
* ```
*
* @param key - The key to check.
* @returns True if object is not a function.
*/
isNotFunction(key: string): boolean;
/**
* Return true if object is not an instance of a class.
*
* @example
* ```js
* container.isNotInstanceOf('my-key', MyClass)
* // True if object associated with 'my-key' is not an instance of MyClass.
* ```
*
* @param key - The key to check.
* @param instance - The class to check against
* @returns
*/
isNotInstanceOf(key: string, instance: any): boolean;
/**
* Return true if object is not an instance of any of the classes.
*
* @example
* ```js
* container.isNotInstanceOfAny('my-key', [MyClass, MyOtherClass])
* // True if object associated with 'my-key' is not an instance of MyClass or MyOtherClass.
* ```
*
* @param key - search key
* @param instances - classes
* @returns
*/
isNotInstanceOfAny(key: string, instances: any[]): boolean;
/**
* Return true if object is not null.
*
* @example
* ```js
* container.isNotNull('my-key')
* // True if container.repository['my-key'] is not null
* ```
*
* @param key - The key to check
* @returns True if object is not null
*/
isNotNull(key: string): boolean;
/**
* Return true if object is not a number.
*
* @example
* ```js
* container.isNumber('my-key')
* // True if container.repository['my-key'] is not a number
* ```
*
* @param key - The key to check
* @returns True if object is not a number
*/
isNotNumber(key: string): boolean;
/**
* Return true if object is not a string.
*
* @example
* ```js
* container.isString('my-key')
* // True if container.repository['my-key'] is not a string
* ```
*
* @param key - The key to check
* @returns True if object is not a string
*/
isNotString(key: string): boolean;
/**
* Return true if object is null.
*
* @example
* ```js
* container.isNull('my-key')
* // True if container.repository['my-key'] is null
* ```
*
* @param key - The key to check
* @returns True if object is null
*/
isNull(key: string): boolean;
/**
* Return true if object is a number.
*
* @example
* ```js
* container.isNumber('my-key')
* // True if container.repository['my-key'] is a number
* ```
*
* @param key - The key to check
* @returns True if object is a number
*/
isNumber(key: string): boolean;
/**
* Return true if object is a string.
*
* @example
* ```js
* container.isString('my-key')
* // True if container.repository['my-key'] is a string
* ```
*
* @param key - The key to check
* @returns True if object is a string
*/
isString(key: string): boolean;
/**
* Return a boolean indicating if the given key's value is true
*
* @example
* ```js
* container.isTrue('my-key')
* // True if container.repository['my-key'] === true
* ```
*
* @param key - The key to check
* @returns True if the key's value is true
*/
isTrue(key: string): boolean;
/**
* Return true if object is not defined.
*
* @example
* ```js
* container.isDefined('my-key')
* // True if container has a 'my-key' entry with a definite value.
* ```
*
* @param key - The key to check.
* @returns True if the key is not defined.
*/
isUndefined(key: string): boolean;
/**
* Merge a supplied value with an existing repository value
*
* @example
* ```js
* container.merge('key', {merge: values})
* ```
*
* @param key - The key of the item to merge
* @param value - The value to merge with the existing value
*/
merge(key: string, value: any): this;
/**
* Merge values onto the container store.
*
* @example
* ```js
* container.mergeStore({test: 'foo'})
* ```
*
* @param values - Values to merge onto the container store
* @returns The container instance
*/
mergeStore(values: Repository): this;
/**
* Mutate a repository item
*
* @example
* ```js
* container.mutate('key', currentValue => modifiedValue)
* ```
*
* @param key - The key of the item to mutate
* @param mutationFn - The mutation function to run on the item
*/
mutate(key: string, mutationFn: (value?: any) => any): this;
/**
* Runs the entire repository through the supplied fn and returns
* the transformed value. The transformed repository replaces the
* original.
*
* @example
* ```js
* container.mutate('key', currentValue => modifiedValue)
* ```
*/
mutateStore(mutationFn: (value?: any) => any): this;
/**
* delete
*
* Delete an entry from the repository
*
* @example
* ```js
* container.remove('my-key')
* // Remove container.repository['my-key']
* ```
*/
remove(key: string): this;
/**
* Set a repository value
*
* @example
* ```js
* container.set('key', value)
* ```
*/
set(key: Array<string> | string, value: any): this;
/**
* Replace the store with an all new set of values
*
* @example
* ```js
* container.setStore({
* new: ['store', 'contents'],
* })
* ```
*/
setStore(repository: Repository): this;
/**
* Retrieve a container item, running it through the supplied fn.
*
* @remarks
* Returns the transformed value.
*
* @example
* ```js
* container.transform('key', currentValue => modifiedValue)
* ```
*
* @param key - The key of the item to transform
* @param fn - The function to transform the item with
*/
transform(key: string, mutationFn: (value?: any) => any): any;
/**
* Runs the entire repository through the supplied fn and returns
* the transformed value.
*
* @example
* ```js
* container.transform(store=> modifiedStore)
* ```
*
* @param fn - Function to run on the repository
* @returns The transformed repository
*/
transformStore(transformFn: (value: any) => any): any;
/**
* Returns unique elements of an array item
*
* @example
* ```js
* container.unique('item')
* ```
*/
unique(key: string): any;
}