@homer0/jimple 4.0.0 → 5.0.0

package/src/helpers/provider.ts

@@ -0,0 +1,42 @@
+import type { Jimple } from '../jimple/index.js';
+import { resourceFactory } from '../factories/index.js';
+
+export type ProviderName = 'provider';
+export type ProviderKey = 'register';
+/**
+ * The function the container will call when the provider is registered.
+ *
+ * @param container  A reference for container where the provider is being registered.
+ * @template ContainerType  The type of the Jimple container (in case it gets
+ *                          subclassed).
+ */
+export type ProviderRegisterFn<ContainerType extends Jimple = Jimple> = (
+  container: ContainerType,
+) => void;
+/**
+ * Generates a function to create providers for a specific type of container.
+ *
+ * @returns A function to create providers.
+ * @template ContainerType  The type of the Jimple container (in case it gets
+ *                          subclassed).
+ */
+export const createProvider = <ContainerType extends Jimple = Jimple>() => {
+  type RegisterFn = ProviderRegisterFn<ContainerType>;
+  const factory = resourceFactory<RegisterFn>();
+  return (register: RegisterFn) => factory('provider', 'register', register);
+};
+/**
+ * Creates a resource to be registered in a Jimple container.
+ *
+ * @example
+ *
+ *   export const myService = provider((c) => {
+ *     c.set('myService', () => new MyService());
+ *   });
+ *
+ */
+export const provider = createProvider();
+/**
+ * A resource that can be registered in a Jimple container.
+ */
+export type Provider = ReturnType<typeof provider>;

package/src/helpers/providerCreator.ts

@@ -0,0 +1,33 @@
+import type { Jimple } from '../jimple/index.js';
+import { resourceCreatorFactory, type GenericCurriedFn } from '../factories/index.js';
+import type { ProviderRegisterFn } from './provider.js';
+/**
+ * Generates a function to create "provider creators" for a specific type of container.
+ *
+ * @returns A function to generate provider creators.
+ * @template ContainerType  The type of the Jimple container (in case it gets
+ *                          subclassed).
+ */
+export const createProviderCreator = <ContainerType extends Jimple = Jimple>() => {
+  type RegisterFn = ProviderRegisterFn<ContainerType>;
+  type ProviderCreatorFn = GenericCurriedFn<RegisterFn>;
+  const factory = resourceCreatorFactory<RegisterFn>();
+  return <CreatorFn extends ProviderCreatorFn>(creator: CreatorFn) =>
+    factory('provider', 'register', creator);
+};
+/**
+ * Generates a "provider creator": a provider that can also be called as a function in
+ * order to create a configured provider.
+ *
+ * @example
+ *
+ *   export const myService = providerCreator((options: Opts = {}) => (c) => {
+ *     c.set('myService', () => new MyService(options));
+ *   });
+ *
+ */
+export const providerCreator = createProviderCreator();
+/**
+ * A function that returns a provider registration function.
+ */
+export type ProviderCreatorFn = Parameters<typeof providerCreator>[0];

package/src/helpers/providers.ts

@@ -0,0 +1,32 @@
+import type { Jimple } from '../jimple/index.js';
+import { resourcesCollectionFactory } from '../factories/index.js';
+import type { ProviderRegisterFn, ProviderName } from './provider.js';
+/**
+ * Generates a function to create a providers collection for a specific type of container.
+ *
+ * @returns A function to create providers collections.
+ * @template ContainerType  The type of the Jimple container (in case it gets
+ *                          subclassed).
+ */
+export const createProviders = <ContainerType extends Jimple = Jimple>() => {
+  type RegisterFn = ProviderRegisterFn<ContainerType>;
+  const factory = resourcesCollectionFactory<ProviderName, RegisterFn>();
+  return factory('provider', 'register');
+};
+/**
+ * Generates a collection of providers. A collection is a dictionary of providers that can
+ * also be used as a provider, and when it gets registered, it will register all of the
+ * providers in the collection.
+ *
+ * @param items  A dictionary of providers.
+ * @example
+ *
+ * <caption>Assuming we already have two service providers...</caption>
+ *
+ *   export const services = providers({
+ *     myServiceProvider,
+ *     myOtherServiceProvider,
+ *   });
+ *
+ */
+export const providers = createProviders();

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './jimple/index.js';
+export * from './factories/index.js';
+export * from './helpers/index.js';

package/src/jimple/index.ts

@@ -0,0 +1,28 @@
+import { Jimple as JimpleMod } from '../jimplemod/index.js';
+
+export class Jimple extends JimpleMod {
+  /**
+   * This is a version of the `get` method that doesn't throw if the key doesn't exist. It
+   * will return `undefined` instead.
+   *
+   * @param key  The key of the parameter or service to return.
+   * @returns The object related to the service or the value of the parameter
+   *          associated with the given key.
+   * @template T  The type of the returned object.
+   */
+  try<T = unknown>(key: string): T | undefined {
+    if (!this.has(key)) {
+      return undefined;
+    }
+
+    return this.get<T>(key);
+  }
+}
+/**
+ * Shorthand for `new Jimple()`.
+ *
+ * @param args  The same parameters as the {@link Jimple} constructor.
+ * @returns A new instance of {@link Jimple}.
+ */
+export const jimple = (...args: ConstructorParameters<typeof Jimple>): Jimple =>
+  new Jimple(...args);

package/src/jimplemod/index.ts

@@ -0,0 +1,8 @@
+// @ts-expect-error - the idea is to have `any` and assert on export.
+import JimpleOriginal from 'jimple';
+import { Container as JimpleContainer } from './jimple.type.js';
+
+const Jimple = JimpleOriginal as typeof JimpleContainer;
+
+export { Jimple };
+export type { JimpleContainer };

package/src/jimplemod/jimple.type.ts

@@ -0,0 +1,93 @@
+/* eslint-disable */
+// @ts-nocheck - This is just a workaround to get the type.
+export class Container {
+  static provider<T extends (arg0: Container) => void>(
+    register: T,
+  ): {
+    register: T;
+  } {}
+  _items: Record<string, unknown>;
+  _instances: Map<string, unknown>;
+  _factories: Set<unknown>;
+  _protected: Set<unknown>;
+  /**
+   * Creates a Jimple Container.
+   *
+   * @param values  An optional object whose keys and values will be associated in the
+   *                container at initialization.
+   */
+  constructor(values?: Record<string, unknown>) {}
+  /**
+   * Return the specified parameter or service. If the service is not built yet, this
+   * function will construct the service injecting all the dependencies needed in it's
+   * definition so the returned object is totally usable on the fly.
+   *
+   * @param key  The key of the parameter or service to return.
+   * @returns The object related to the service or the value of the parameter
+   *          associated with the given key.
+   * @template T  The type of the returned object.
+   * @throws If the key does not exist.
+   */
+  get<T = unknown>(key: string): T {}
+  /**
+   * Defines a new parameter or service.
+   *
+   * @param key    The key of the parameter or service to be defined.
+   * @param value  The value of the parameter or a function that receives the container
+   *               as parameter and constructs the service.
+   */
+  set(key: string, value: unknown): void {}
+  /**
+   * Returns if a service or parameter with the informed key is already defined in the
+   * container.
+   *
+   * @param key  The key of the parameter or service to be checked.
+   * @returns If the key exists in the container or not.
+   */
+  has(key: string): boolean {}
+  /**
+   * Defines a service as a factory, so the instances are not cached in the service and
+   * that function is always called.
+   *
+   * @param fn  The function that constructs the service that is a factory.
+   * @returns The same function passed as parameter.
+   */
+  factory<C = this>(fn: (arg0: C) => unknown): (arg0: C) => unknown {}
+  /**
+   * Defines a function as a parameter, so that function is not considered a service.
+   *
+   * @param fn  The function to not be considered a service.
+   * @returns The same function passed as parameter.
+   */
+  protect<T extends () => unknown>(fn: T): T {}
+  /**
+   * Return all the keys registered in the container.
+   */
+  keys(): string[] {}
+  /**
+   * Extends a service already registered in the container.
+   *
+   * @param key  The key of the service to be extended.
+   * @param fn   The function that will be used to extend the service.
+   * @throws If the key is not already defined.
+   * @throws If the key saved in the container does not correspond to a service.
+   * @throws If the function passed it not...well, a function.
+   */
+  extend<C = this>(key: string, fn: (arg0: unknown, arg1: C) => unknown): void {}
+  /**
+   * Uses an provider to extend the service, so it's easy to split the service and
+   * parameter definitions across the system.
+   *
+   * @param provider  The provider to be used to register services and parameters in
+   *                  this container.
+   */
+  register<C = this>(provider: { register: (arg0: C) => void }): void {}
+  /**
+   * Returns the raw value of a service or parameter. So, in the case of a service,
+   * for example, the value returned is the function used to construct the service.
+   *
+   * @param key  The key of the service or parameter to return.
+   * @throws If the key does not exist in the container.
+   */
+  raw<T = unknown>(key: string): T {}
+}