jimpex 7.0.2 → 9.0.0

package/dist/services/frontend/frontendFs.js

@@ -0,0 +1,103 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+var frontendFs_exports = {};
+__export(frontendFs_exports, {
+  FrontendFs: () => FrontendFs,
+  frontendFsProvider: () => frontendFsProvider
+});
+module.exports = __toCommonJS(frontendFs_exports);
+var import_promises = __toESM(require("fs/promises"));
+var import_utils = require("../../utils");
+class FrontendFs {
+  /**
+   * @param options  The options to construct the service.
+   */
+  constructor({ inject: { pathUtils } }) {
+    /**
+     * The service that generates the relative paths.
+     */
+    __publicField(this, "_pathUtils");
+    this._pathUtils = pathUtils;
+  }
+  /**
+   * Deletes a file from the file system.
+   *
+   * @param filepath  The path to the file.
+   */
+  delete(filepath) {
+    return import_promises.default.unlink(this.getAppPath(filepath));
+  }
+  /**
+   * Reads a file from the file system.
+   *
+   * @param filepath  The path to the file.
+   * @param encoding  The text encoding in which the file should be read.
+   */
+  read(filepath, encoding = "utf-8") {
+    return import_promises.default.readFile(this.getAppPath(filepath), encoding);
+  }
+  /**
+   * Writes a file on the file system.
+   *
+   * @param filepath  The path to the file.
+   * @param content   The contents of the file.
+   */
+  write(filepath, content) {
+    return import_promises.default.writeFile(this.getAppPath(filepath), content);
+  }
+  /**
+   * Utility method to get the path of a file relative to the application executable.
+   *
+   * @param filepath  The path to the file.
+   */
+  getAppPath(filepath) {
+    return this._pathUtils.joinFrom("app", filepath);
+  }
+}
+const frontendFsProvider = (0, import_utils.provider)((app) => {
+  app.set(
+    "frontendFs",
+    () => new FrontendFs({
+      inject: {
+        pathUtils: app.get("pathUtils")
+      }
+    })
+  );
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FrontendFs,
+  frontendFsProvider
+});
+//# sourceMappingURL=frontendFs.js.map

package/dist/services/frontend/frontendFs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/services/frontend/frontendFs.ts"],"sourcesContent":["import fs from 'fs/promises';\nimport { provider } from '../../utils';\nimport type { PathUtils } from '../../types';\n/**\n * The options to construct a {@link FrontendFs}.\n *\n * @group Services/FrontendFs\n */\nexport type FrontendFsOptions = {\n  /**\n   * A dictionary with the dependencies to inject.\n   */\n  inject: {\n    pathUtils: PathUtils;\n  };\n};\n/**\n * This service allows the application to easily work with the filesystem. The idea behind\n * centralizing this functionalities into a service is that is pretty common to have\n * bundling tools to generate the frontend, and on that process files can have different\n * paths or not even be generated all. The service can be extended/overwritten to\n * accommodate any requirements and avoid having to update or add `if`s to every `fs` call\n * the application does.\n * Another _'feature'_ of this service is that all the paths are relative to the directory\n * where the app executable is located, so you don't have to remember the relative path\n * from the place you are accessing a file to the place where it's located.\n *\n * @group Services\n * @group Services/FrontendFs\n */\nexport class FrontendFs {\n  /**\n   * The service that generates the relative paths.\n   */\n  protected readonly _pathUtils: PathUtils;\n  /**\n   * @param options  The options to construct the service.\n   */\n  constructor({ inject: { pathUtils } }: FrontendFsOptions) {\n    this._pathUtils = pathUtils;\n  }\n  /**\n   * Deletes a file from the file system.\n   *\n   * @param filepath  The path to the file.\n   */\n  delete(filepath: string): Promise<void> {\n    return fs.unlink(this.getAppPath(filepath));\n  }\n  /**\n   * Reads a file from the file system.\n   *\n   * @param filepath  The path to the file.\n   * @param encoding  The text encoding in which the file should be read.\n   */\n  read(filepath: string, encoding: BufferEncoding = 'utf-8'): Promise<string> {\n    return fs.readFile(this.getAppPath(filepath), encoding);\n  }\n  /**\n   * Writes a file on the file system.\n   *\n   * @param filepath  The path to the file.\n   * @param content   The contents of the file.\n   */\n  write(filepath: string, content: Parameters<typeof fs.writeFile>[1]): Promise<void> {\n    return fs.writeFile(this.getAppPath(filepath), content);\n  }\n  /**\n   * Utility method to get the path of a file relative to the application executable.\n   *\n   * @param filepath  The path to the file.\n   */\n  protected getAppPath(filepath: string): string {\n    return this._pathUtils.joinFrom('app', filepath);\n  }\n}\n/**\n * The service provider that once registered on the container will set an instance of\n * {@link FrontendFs} as the `frontendFs` service.\n *\n * @example\n *\n *   // Register it on the container\n *   container.register(frontendFsProvider);\n *   // Getting access to the service instance\n *   const frontendFs = container.get<FrontendFs>('frontendFs');\n *\n * @group Providers\n * @group Services/FrontendFs\n */\nexport const frontendFsProvider = provider((app) => {\n  app.set(\n    'frontendFs',\n    () =>\n      new FrontendFs({\n        inject: {\n          pathUtils: app.get<PathUtils>('pathUtils'),\n        },\n      }),\n  );\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAAe;AACf,mBAAyB;AA6BlB,MAAM,WAAW;AAAA;AAAA;AAAA;AAAA,EAQtB,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAsB;AAJ1D;AAAA;AAAA;AAAA,wBAAmB;AAKjB,SAAK,aAAa;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,UAAiC;AACtC,WAAO,gBAAAA,QAAG,OAAO,KAAK,WAAW,QAAQ,CAAC;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,KAAK,UAAkB,WAA2B,SAA0B;AAC1E,WAAO,gBAAAA,QAAG,SAAS,KAAK,WAAW,QAAQ,GAAG,QAAQ;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,UAAkB,SAA4D;AAClF,WAAO,gBAAAA,QAAG,UAAU,KAAK,WAAW,QAAQ,GAAG,OAAO;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMU,WAAW,UAA0B;AAC7C,WAAO,KAAK,WAAW,SAAS,OAAO,QAAQ;AAAA,EACjD;AACF;AAeO,MAAM,yBAAqB,uBAAS,CAAC,QAAQ;AAClD,MAAI;AAAA,IACF;AAAA,IACA,MACE,IAAI,WAAW;AAAA,MACb,QAAQ;AAAA,QACN,WAAW,IAAI,IAAe,WAAW;AAAA,MAC3C;AAAA,IACF,CAAC;AAAA,EACL;AACF,CAAC;","names":["fs"]}

package/dist/services/frontend/index.d.mts

@@ -0,0 +1,40 @@
+import * as _homer0_jimple from '@homer0/jimple';
+import { J as Jimpex } from '../../index-efeb437e.js';
+export { FrontendFs, FrontendFsOptions, frontendFsProvider } from './frontendFs.mjs';
+import '../../types/express.mjs';
+import 'express';
+import '../../types/http.mjs';
+import 'https';
+import 'http';
+import 'spdy';
+import 'node-fetch';
+import '../../types/utils.mjs';
+import '@homer0/path-utils';
+import '@homer0/simple-logger';
+import '@homer0/simple-config';
+import '@homer0/events-hub';
+import 'fs/promises';
+
+/**
+ * Registers all the frontend services on the container.
+ *
+ * - {@link FrontendFs | frontendFs}
+ *
+ * @example
+ *
+ *   // Register the collection on the container
+ *   container.register(frontendServicesProvider);
+ *   // Getting access to one the services instance
+ *   const frontendFs = container.get<FrontendFs>('frontendFs');
+ *
+ * @group Providers
+ */
+declare const frontendServicesProvider: {
+    frontendFsProvider: _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>;
+} & Record<string, _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>> & {
+    provider: true;
+} & {
+    register: _homer0_jimple.ProviderRegisterFn<Jimpex>;
+} & Record<string, unknown>;
+
+export { frontendServicesProvider };

package/dist/services/frontend/index.d.ts

@@ -0,0 +1,40 @@
+import * as _homer0_jimple from '@homer0/jimple';
+import { J as Jimpex } from '../../index-b2a04c78.js';
+export { FrontendFs, FrontendFsOptions, frontendFsProvider } from './frontendFs.js';
+import '../../types/express.js';
+import 'express';
+import '../../types/http.js';
+import 'https';
+import 'http';
+import 'spdy';
+import 'node-fetch';
+import '../../types/utils.js';
+import '@homer0/path-utils';
+import '@homer0/simple-logger';
+import '@homer0/simple-config';
+import '@homer0/events-hub';
+import 'fs/promises';
+
+/**
+ * Registers all the frontend services on the container.
+ *
+ * - {@link FrontendFs | frontendFs}
+ *
+ * @example
+ *
+ *   // Register the collection on the container
+ *   container.register(frontendServicesProvider);
+ *   // Getting access to one the services instance
+ *   const frontendFs = container.get<FrontendFs>('frontendFs');
+ *
+ * @group Providers
+ */
+declare const frontendServicesProvider: {
+    frontendFsProvider: _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>;
+} & Record<string, _homer0_jimple.Resource<"provider", "register", _homer0_jimple.ProviderRegisterFn<Jimpex>>> & {
+    provider: true;
+} & {
+    register: _homer0_jimple.ProviderRegisterFn<Jimpex>;
+} & Record<string, unknown>;
+
+export { frontendServicesProvider };

package/dist/services/frontend/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var frontend_exports = {};
+__export(frontend_exports, {
+  frontendServicesProvider: () => frontendServicesProvider
+});
+module.exports = __toCommonJS(frontend_exports);
+var import_utils = require("../../utils");
+var import_frontendFs = require("./frontendFs");
+__reExport(frontend_exports, require("./frontendFs"), module.exports);
+const frontendServicesProvider = (0, import_utils.providers)({
+  frontendFsProvider: import_frontendFs.frontendFsProvider
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  frontendServicesProvider,
+  ...require("./frontendFs")
+});
+//# sourceMappingURL=index.js.map

package/dist/services/frontend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/services/frontend/index.ts"],"sourcesContent":["import { providers } from '../../utils';\nimport { frontendFsProvider } from './frontendFs';\n/**\n * Registers all the frontend services on the container.\n *\n * - {@link FrontendFs | frontendFs}\n *\n * @example\n *\n *   // Register the collection on the container\n *   container.register(frontendServicesProvider);\n *   // Getting access to one the services instance\n *   const frontendFs = container.get<FrontendFs>('frontendFs');\n *\n * @group Providers\n */\nexport const frontendServicesProvider = providers({\n  frontendFsProvider,\n});\n\nexport * from './frontendFs';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAA0B;AAC1B,wBAAmC;AAmBnC,6BAAc,yBApBd;AAgBO,MAAM,+BAA2B,wBAAU;AAAA,EAChD;AACF,CAAC;","names":[]}

package/dist/services/html/htmlGenerator.d.mts

@@ -0,0 +1,237 @@
+import * as _homer0_jimple from '@homer0/jimple';
+import { J as Jimpex } from '../../index-efeb437e.js';
+import { SimpleLogger } from '@homer0/simple-logger';
+import { SimpleConfig } from '@homer0/simple-config';
+import { FrontendFs } from '../frontend/frontendFs.mjs';
+import { DeferredPromise } from '@homer0/deferred';
+import '../../types/express.mjs';
+import 'express';
+import '../../types/http.mjs';
+import 'https';
+import 'http';
+import 'spdy';
+import 'node-fetch';
+import '../../types/utils.mjs';
+import '@homer0/path-utils';
+import '@homer0/events-hub';
+import 'fs/promises';
+
+/**
+ * The options to customize a {@link HTMLGenerator} instance.
+ *
+ * @group Services/HTMLGenerator
+ */
+type HTMLGeneratorOptions = {
+    /**
+     * The name of the file it should use as template.
+     *
+     * @default 'index.tpl.html'
+     */
+    template: string;
+    /**
+     * The name of the generated file.
+     *
+     * @default 'index.html'
+     */
+    file: string;
+    /**
+     * If `true`, it won't log messages on the terminal when generating the file.
+     *
+     * @default false
+     */
+    silent: boolean;
+    /**
+     * Whether or not to delete the tempalte after generating the file.
+     *
+     * @default true
+     */
+    deleteTemplateAfter: boolean;
+    /**
+     * The placeholder string where the information will be written.
+     *
+     * @default /\{\{appConfi(?:guration)?\}\}/
+     */
+    replacePlaceholder: string | RegExp;
+    /**
+     * A regular expression for dynamic placeholders that will be replaced by values when
+     * the file is generated.
+     *
+     * @default /\{\{(.*?)\}\}/gi
+     */
+    placeholderExpression: RegExp;
+    /**
+     * The name of the variable that will have the information on the file.
+     *
+     * @default 'appConfig'
+     */
+    variableName: string;
+    /**
+     * A list of settings from the app configuration that will be used as the information to
+     * inject on the file.
+     *
+     * @default ['features', 'version', 'postMessagesPrefix']
+     */
+    configKeys: string[];
+};
+/**
+ * An external service that can be used to provide the values the generator will replace
+ * in the template.
+ *
+ * @group Services/HTMLGenerator
+ */
+type HTMLGeneratorValuesService = {
+    /**
+     * A function that will be called to get the values to replace in the template.
+     *
+     * @param options  The service customization options.
+     */
+    getValues: (options: HTMLGeneratorOptions) => Promise<Record<string, unknown>>;
+};
+/**
+ * The options to construct a {@link HTMLGenerator}.
+ *
+ * @group Services/HTMLGenerator
+ */
+type HTMLGeneratorConstructorOptions = Partial<HTMLGeneratorOptions> & {
+    /**
+     * A dictionary with the dependencies to inject.
+     */
+    inject: {
+        config: SimpleConfig;
+        logger: SimpleLogger;
+        frontendFs: FrontendFs;
+        /**
+         * A service that can provide the values to replace in the template. If specified, the
+         * values from `configKeys` will be ignored.
+         */
+        valuesService?: HTMLGeneratorValuesService;
+    };
+};
+/**
+ * Custom options for the provider that will register an instance of {@link HTMLGenerator}
+ * as a service.
+ *
+ * @group Services/HTMLGenerator
+ */
+type HTMLGeneratorProviderOptions = Partial<HTMLGeneratorOptions> & {
+    /**
+     * The name that will be used to register the service on the container. This is to allow
+     * multiple "instances" of the service to be created.
+     *
+     * @default 'htmlGenerator'
+     */
+    serviceName?: string;
+    /**
+     * The name of a service that the generator will use in order to read the values that
+     * will be replaced on the template. If the service is available, the values from
+     * `configKeys` will be ignored.
+     *
+     * @default 'htmlGeneratorValues'
+     */
+    valuesServiceName?: string;
+};
+/**
+ * This is a utility service that generates an HTML file with custom information when the
+ * application is started.
+ *
+ * @group Services
+ * @group Services/HTMLGenerator
+ */
+declare class HTMLGenerator {
+    /**
+     * The service customization options.
+     */
+    protected readonly _options: HTMLGeneratorOptions;
+    /**
+     * The application configuration service, to get the settings specified by the
+     * `configKeys` option.
+     */
+    protected readonly _config: SimpleConfig;
+    /**
+     * The service that logs messages on the terminal, in case the `silent` option is `false`.
+     */
+    protected readonly _logger: SimpleLogger;
+    /**
+     * The service that interacts with the filesystem.
+     */
+    protected readonly _frontendFs: FrontendFs;
+    /**
+     * A service that can provide values to be replaced in the template.
+     */
+    protected readonly _valuesService?: HTMLGeneratorValuesService;
+    /**
+     * Whether or not the file was already generated.
+     */
+    protected _fileReady: boolean;
+    /**
+     * A deferred promise to return when another service asks if the file has been
+     * generated. Once this sevice finishes generating the file, the promise will be
+     * resolved for all implementations that hold a reference to this deferred.
+     */
+    protected _fileDeferred?: DeferredPromise<void>;
+    /**
+     * @param options  The options to construct the class.
+     * @throws If `valuesService` is specified but it doesn't have a `getValues`
+     *         method.
+     */
+    constructor({ inject: { config, logger, frontendFs, valuesService }, ...options }: HTMLGeneratorConstructorOptions);
+    /**
+     * Gets a promise that will be resolved when the file has been generated.
+     */
+    whenReady(): Promise<void>;
+    /**
+     * Generates the HTML file.
+     */
+    generateHTML(): Promise<void>;
+    /**
+     * Gets the customization options.
+     */
+    get options(): Readonly<HTMLGeneratorOptions>;
+    /**
+     * Helper method to get the values that will be replaced in the template. If a "values
+     * service" was specified in the constructor, it will get the values from there,
+     * otherwise, it will use the `configKeys` option to get the values from the
+     * application configuration.
+     */
+    protected _getValues(): Promise<Record<string, unknown>>;
+    /**
+     * Processes the HTML template by replacing the placeholders with the actual values.
+     *
+     * @param template  The template for the HTML file.
+     * @param values    The values dictionary that should be replaced in the template.
+     */
+    protected _processHTML(template: string, values: Record<string, unknown>): string;
+}
+/**
+ * The service provider that once registered on the container will set an instance of
+ * {@link HTMLGenerator} as the `htmlGenerator` service. it will also hook itself to the
+ * `after-start` event of the application in order to trigger the generator of the HTML
+ * file.
+ *
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   // Register it on the container
+ *   container.register(htmlGeneratorProvider);
+ *   // Getting access to the service instance
+ *   const htmlGenerator = container.get<HTMLGenerator>('htmlGenerator');
+ *
+ * @example
+ *
+ * <caption>Using with custom options</caption>
+ *
+ *   container.register(
+ *     htmlGeneratorProvider({
+ *       serviceName: 'myHtmlGenerator',
+ *       valuesServiceName: 'myValuesService',
+ *       template: 'my-template.tpl.html',
+ *     }),
+ *   );
+ *
+ * @group Providers
+ * @group Services/HTMLGenerator
+ */
+declare const htmlGeneratorProvider: _homer0_jimple.ResourceCreator<"provider", "register", (options?: HTMLGeneratorProviderOptions) => (app: Jimpex) => void, _homer0_jimple.ProviderRegisterFn<Jimpex>>;
+
+export { HTMLGenerator, HTMLGeneratorConstructorOptions, HTMLGeneratorOptions, HTMLGeneratorProviderOptions, HTMLGeneratorValuesService, htmlGeneratorProvider };