@armscye/container 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @armscye/container
 
-> A collection of shared standard TypeScript definitions.
+> A collection of shared standard TypeScript definitions (@container).
 
 ## Installation
 
@@ -15,3 +15,166 @@ or using yarn:
 ```sh
 yarn add @armscye/container --dev
 ```
+
+## Reference
+
+### ClassProvider `Interface`
+
+Configures the `Container` to return an instance of `useClass` for a token.
+
+```ts
+interface ClassProvider<T = any> {
+  provide: ProviderToken;
+
+  useClass: NoArgument<T>;
+
+  shared?: boolean;
+}
+```
+
+**Properties**
+
+| Property                  | Description                                |
+| ------------------------- | ------------------------------------------ |
+| provide: ProviderToken    | A provider token.                          |
+| useClass: NoArgument<any> | A class to instantiate for the `token`.    |
+| shared?: boolean          | When true, the created instance is cached. |
+
+### Container `Interface`
+
+Describes the interface of a container that exposes methods to read its entries.
+
+```ts
+interface Container {
+  get<T>(token: ProviderToken): T;
+
+  has(token: ProviderToken): boolean;
+}
+```
+
+**Methods**
+
+    get(token: ProviderToken): T
+
+Retrieves an entry from the container based on its provider token.
+
+_Parameters_
+
+- `token`: The unique identifier of the entry to retrieve.
+
+_Returns_
+
+The entry associated with the provided token, if found.
+
+_Throws_
+
+`Error` if the entry doesn't exist or an error occurs during retrieval.
+
+    has(token: ProviderToken): boolean
+
+Checks whether an entry for a specific provider token exists in the container.
+
+_Parameters_
+
+`token`: The unique identifier of the entry to check for.
+
+_Returns_
+
+`true` if an entry for the provided token exists, `false` otherwise.
+
+### ExistingProvider `Interface`
+
+Configures the `Container` to return a value of another `useExisting` token.
+
+```ts
+interface ExistingProvider<T = any> {
+  provide: ProviderToken;
+
+  useExisting: T;
+
+  shared?: boolean;
+}
+```
+
+**Properties**
+
+| Property                   | Description                                |
+| -------------------------- | ------------------------------------------ |
+| provide: ProviderToken     | A provider token.                          |
+| useExisting: ProviderToken | Existing `token` to return.                |
+| shared?: boolean           | When true, the created instance is cached. |
+
+### FactoryProvider `Interface`
+
+Configures the `Container` to return a value by invoking a `useFactory` function.
+
+```ts
+interface FactoryProvider<T = any> {
+  provide: ProviderToken;
+
+  useFactory: Factory<T>;
+
+  shared?: boolean;
+}
+```
+
+**Properties**
+
+| Property               | Description                                                       |
+| ---------------------- | ----------------------------------------------------------------- |
+| provide: ProviderToken | A provider token.                                                 |
+| useFactory: Factory    | A factory function to invoke to create an object for the `token`. |
+| shared?: boolean       | When true, the created instance is cached.                        |
+
+### Factory `Type`
+
+A function to invoke to create an object. The function is invoked with an instance of the container in order to access required dependencies.
+
+```ts
+type Factory<T = any> = (container: Container) => T;
+```
+
+### ProviderToken `Type`
+
+Token that can be used to retrieve an instance from a container.
+
+```ts
+type ProviderToken = string | symbol;
+```
+
+### Provider `Type`
+
+Describes how the `Container` should be configured.
+
+```ts
+type Provider<T = any> =
+  | ValueProvider<T>
+  | ClassProvider<T>
+  | FactoryProvider<T>
+  | ExistingProvider<T>;
+```
+
+### ValueProvider `Interface`
+
+Configures the `Container` to return a value for a token.
+
+```ts
+interface ValueProvider<T = any> {
+  provide: ProviderToken;
+
+  useValue: T;
+}
+```
+
+**Properties**
+
+| Property               | Description                                                 |
+| ---------------------- | ----------------------------------------------------------- |
+| provide: ProviderToken | A provider token.                                           |
+| useValue: any          | The actual value that will be provided for the given token. |
+
+## License
+
+This project is licensed under the **MIT license**.
+
+See [LICENSE](LICENSE) for more information.

package/dist/{class-provider.interface.d.ts → class-provider.d.ts}

@@ -1,7 +1,7 @@
 import { NoArgument } from '@armscye/core';
-import { ProviderToken } from './provider-token.interface';
+import { ProviderToken } from './provider-token';
 /**
- * Configures the `Container` to return an instance of `useClass` for a token.
+ * Configures the `Container` to return a value by instantiating `useClass` class.
  */
 export interface ClassProvider<T = any> {
     /**
@@ -12,4 +12,8 @@ export interface ClassProvider<T = any> {
      * Class to instantiate for the `token`.
      */
     useClass: NoArgument<T>;
+    /**
+     * Whether the created instance should be cached.
+     */
+    shared?: boolean;
 }

package/dist/{container.interface.d.ts → container.d.ts}

@@ -1,4 +1,4 @@
-import { ProviderToken } from './provider-token.interface';
+import { ProviderToken } from './provider-token';
 /**
  * Describes the interface of a container that exposes methods to read its entries.
  */

package/dist/{existing-provider.interface.d.ts → existing-provider.d.ts}

@@ -1,4 +1,4 @@
-import { ProviderToken } from './provider-token.interface';
+import { ProviderToken } from './provider-token';
 /**
  * Configures the `Container` to return a value of another `useExisting` token.
  */
@@ -11,4 +11,8 @@ export interface ExistingProvider<T = any> {
      * Existing `token` to return.
      */
     useExisting: T;
+    /**
+     * Whether the created instance should be cached.
+     */
+    shared?: boolean;
 }

package/dist/{factory-provider.interface.d.ts → factory-provider.d.ts}

@@ -1,5 +1,5 @@
-import { Factory } from './factory.interface';
-import { ProviderToken } from './provider-token.interface';
+import { Factory } from './factory';
+import { ProviderToken } from './provider-token';
 /**
  * Configures the `Container` to return a value by invoking a `useFactory` function.
  */
@@ -13,4 +13,8 @@ export interface FactoryProvider<T = any> {
      * invoked with resolved values of token`s from an instance of the container.
      */
     useFactory: Factory<T>;
+    /**
+     * Whether the created instance should be cached.
+     */
+    shared?: boolean;
 }

package/dist/{factory.interface.d.ts → factory.d.ts}

@@ -1,4 +1,4 @@
-import { Container } from './container.interface';
+import { Container } from './container';
 /**
  * Represents type for a factory. A factory is a function that is able to create an object.
  * It is provided with an instance of the container in order to access required dependencies.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export * from './class-provider.interface';
-export * from './container.interface';
-export * from './existing-provider.interface';
-export * from './factory-provider.interface';
-export * from './factory.interface';
-export * from './provider-token.interface';
-export * from './provider.interface';
-export * from './value-provider.interface';
+export * from './class-provider';
+export * from './container';
+export * from './existing-provider';
+export * from './factory-provider';
+export * from './factory';
+export * from './provider-token';
+export * from './provider';
+export * from './value-provider';

package/dist/provider.d.ts

@@ -0,0 +1,5 @@
+import { ClassProvider } from './class-provider';
+import { ExistingProvider } from './existing-provider';
+import { FactoryProvider } from './factory-provider';
+import { ValueProvider } from './value-provider';
+export type Provider<T = any> = ValueProvider<T> | ClassProvider<T> | FactoryProvider<T> | ExistingProvider<T>;

package/dist/{value-provider.interface.d.ts → value-provider.d.ts}

@@ -1,4 +1,4 @@
-import { ProviderToken } from './provider-token.interface';
+import { ProviderToken } from './provider-token';
 /**
  * Configures the `Container` to return a value for a token.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@armscye/container",
-  "version": "0.2.0",
-  "description": "A collection of shared standard TypeScript definitions",
+  "version": "0.4.0",
+  "description": "A collection of shared standard TypeScript definitions (@container)",
   "author": "Augustus Kamau",
   "license": "MIT",
   "types": "./dist/index.d.ts",
@@ -11,10 +11,11 @@
   "keywords": [
     "armscye",
     "typescript",
-    "types"
+    "types",
+    "container"
   ],
   "dependencies": {
-    "@armscye/core": "^0.1.0"
+    "@armscye/core": "^0.3.0"
   },
   "homepage": "https://github.com/armscye/armscye#readme",
   "repository": {
@@ -27,5 +28,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "3f346ded1e7a06cf1afac1ba29a6e4f5377d4664"
+  "gitHead": "a26e3829ccbd43eae0ab1a1dd165af7ae7b355c1"
 }

package/dist/provider.interface.d.ts

@@ -1,5 +0,0 @@
-import { ClassProvider } from './class-provider.interface';
-import { ExistingProvider } from './existing-provider.interface';
-import { FactoryProvider } from './factory-provider.interface';
-import { ValueProvider } from './value-provider.interface';
-export type Provider<T = any> = ValueProvider<T> | ClassProvider<T> | FactoryProvider<T> | ExistingProvider<T>;