feat: existsIn, appDependsOn() + moduleDependsOn()

egomobile · Feb 9, 2024 · c4163b3 · c4163b3
1 parent cc51f91
commit c4163b3
Show file tree

Hide file tree

Showing 10 changed files with 291 additions and 31 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Change Log (@egomobile/documentation)
 
+## 0.7.0
+
+- add `appDependsOn()` and `moduleDependsOn()` function
+- add `existsIn` props to `DependencyItemWithInfo` and `ISerializableDependencyItemWithInfo` based items
+- fix documentation
+
 ## 0.6.0
 
 - add optional `entities` prop to `IDependencyInformationEntity`

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@egomobile/documentation",
-    "version": "0.6.0",
+    "version": "0.7.0",
     "description": "Tools for documenting (TypeScript) code.",
     "main": "lib/index.js",
     "engines": {

diff --git a/src/decorators/DependsOn.ts b/src/decorators/DependsOn.ts
@@ -15,8 +15,8 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with this program. If not, see <http://www.gnu.org/licenses/>.
 
-import type { IDependencyInformation, IParameterDependencyItem, IPropertyDependencyItem, IMethodDependencyItem, DependencyInfoResolver, DependencyInfoCollectionArg } from "../types";
-import type { ClassPropKey, CreateDependsOnHelpersFunc, Nilable, Optional } from "../types/internal";
+import type { IDependencyInformation, IParameterDependencyItem, IPropertyDependencyItem, IMethodDependencyItem, DependencyInfoResolver, DependencyInfoCollectionArg, IStackInfo } from "../types";
+import type { ClassPropKey, CreateDependsOnHelpersFunc, Nilable, Nullable, Optional } from "../types/internal";
 
 /**
  * Adds meta for a class, property, method or parameter
@@ -100,6 +100,9 @@ export function DependsOn(
     dependenciesOrResolver?: Nilable<DependencyInfoCollectionArg>
 ): any {
     const createDependsOnHelpers: CreateDependsOnHelpersFunc = require("../utils/internal").createDependsOnHelpers;
+    const tryGetStackInfo = require("../utils/internal").tryGetStackInfo;
+
+    const stackInfo: Nullable<IStackInfo | false> = tryGetStackInfo();
 
     const {
         addItem
@@ -117,7 +120,10 @@ export function DependsOn(
                 "type": "method"
             };
 
-            addItem(newMethodItem);
+            addItem({
+                "existsIn": stackInfo,
+                "item": newMethodItem
+            });
         };
 
         const addAsParameter = () => {
@@ -131,7 +137,10 @@ export function DependsOn(
                 "type": "parameter"
             };
 
-            addItem(newParameterItem);
+            addItem({
+                "existsIn": stackInfo,
+                "item": newParameterItem
+            });
         };
 
         const addAsProperty = () => {
@@ -143,7 +152,10 @@ export function DependsOn(
                 "type": "property"
             };
 
-            addItem(newPropertyItem);
+            addItem({
+                "existsIn": stackInfo,
+                "item": newPropertyItem
+            });
         };
 
         const addWith3Args = () => {
@@ -176,7 +188,8 @@ export function DependsOn(
                 classDependsOn(
                     target,
                     infoOrResolver,
-                    dependenciesOrResolver
+                    dependenciesOrResolver,
+                    stackInfo
                 );
             }
         }

diff --git a/src/functions/dependsOn.ts b/src/functions/dependsOn.ts
@@ -13,9 +13,60 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with this program. If not, see <http://www.gnu.org/licenses/>.
 
-import type { DependencyInfoCollectionArg, DependencyInfoResolver, IClassDependencyItem, IDependencyInformation, IFunctionDependencyItem } from "../types";
+import type { DependencyInfoCollectionArg, DependencyInfoResolver, IClassDependencyItem, IDependencyInformation, IFunctionDependencyItem, IModuleDependencyItem, IStackInfo } from "../types";
 import type { Constructor, CreateDependsOnHelpersFunc, Func, Nilable } from "../types/internal";
 
+/**
+ * Adds dependency information for current app.
+ *
+ * @example
+ * ```
+ * import {
+ *   appDependsOn,
+ *   getDependencies
+ * } from "@egomobile/documentation"
+ *
+ * appDependsOn(
+ *   {
+ *     // your information here...
+ *   }
+ * )
+ *
+ * console.log(
+ *   getDependencies()
+ * )
+ * ```
+ *
+ * @param {IDependencyInformation|DependencyInfoResolver} infoOrResolver The dependency information or the function that resolves it.
+ * @param {Nilable<DependenciesArg>} [dependenciesOrResolver] The custom collection for the dependency info items or the function that resolves it.
+ * @param {Nilable<IStackInfo|false>} [stackInfo] Custom stack information.
+ *
+ * @throws ReferenceError No CommonJS based main module found.
+ */
+export function appDependsOn(
+    infoOrResolver: IDependencyInformation | DependencyInfoResolver,
+    dependenciesOrResolver?: Nilable<DependencyInfoCollectionArg>,
+    stackInfo?: Nilable<IStackInfo | false>
+) {
+    const mainModule = require.main;
+    if (!mainModule) {
+        throw new ReferenceError("no main module found");
+    }
+
+    const tryGetStackInfo = require("../utils/internal").tryGetStackInfo;
+
+    if (!stackInfo) {
+        stackInfo = tryGetStackInfo();
+    }
+
+    moduleDependsOn(
+        mainModule,
+        infoOrResolver,
+        dependenciesOrResolver,
+        stackInfo
+    );
+}
+
 /**
  * Adds dependency information for a class.
  *
@@ -31,7 +82,7 @@ import type { Constructor, CreateDependsOnHelpersFunc, Func, Nilable } from "../
  * }
  *
  * classDependsOn(
- *   MyClass
+ *   MyClass,
  *   {
  *     // your information here...
  *   }
@@ -45,14 +96,21 @@ import type { Constructor, CreateDependsOnHelpersFunc, Func, Nilable } from "../
  * @param {Constructor<any>} classConstructor The class constructor.
  * @param {IDependencyInformation|DependencyInfoResolver} infoOrResolver The dependency information or the function that resolves it.
  * @param {Nilable<DependenciesArg>} [dependenciesOrResolver] The custom collection for the dependency info items or the function that resolves it.
+ * @param {Nilable<IStackInfo|false>} [stackInfo] Custom stack information.
  */
 export function classDependsOn(
     classConstructor: Constructor<any>,
     infoOrResolver: IDependencyInformation | DependencyInfoResolver,
-    dependenciesOrResolver?: Nilable<DependencyInfoCollectionArg>
+    dependenciesOrResolver?: Nilable<DependencyInfoCollectionArg>,
+    stackInfo?: Nilable<IStackInfo | false>
 ) {
     const createDependsOnHelpers: CreateDependsOnHelpersFunc =
         require("../utils/internal").createDependsOnHelpers;
+    const tryGetStackInfo = require("../utils/internal").tryGetStackInfo;
+
+    if (!stackInfo) {
+        stackInfo = tryGetStackInfo();
+    }
 
     const {
         addItem
@@ -63,7 +121,10 @@ export function classDependsOn(
         "type": "class"
     };
 
-    addItem(newClassItem);
+    addItem({
+        "existsIn": stackInfo ?? null,
+        "item": newClassItem
+    });
 }
 
 /**
@@ -81,7 +142,7 @@ export function classDependsOn(
  * }
  *
  * functionDependsOn(
- *   myFunction
+ *   myFunction,
  *   {
  *     // your information here...
  *   }
@@ -95,14 +156,21 @@ export function classDependsOn(
  * @param {Func} func The function.
  * @param {IDependencyInformation|DependencyInfoResolver} infoOrResolver The dependency information or the function that resolves it.
  * @param {Nilable<DependenciesArg>} [dependenciesOrResolver] The custom collection for the dependency info items or the function that resolves it.
+ * @param {Nilable<IStackInfo|false>} [stackInfo] Custom stack information.
  */
 export function functionDependsOn(
     func: Func,
     infoOrResolver: IDependencyInformation | DependencyInfoResolver,
-    dependenciesOrResolver?: Nilable<DependencyInfoCollectionArg>
+    dependenciesOrResolver?: Nilable<DependencyInfoCollectionArg>,
+    stackInfo?: Nilable<IStackInfo | false>
 ) {
     const createDependsOnHelpers: CreateDependsOnHelpersFunc =
         require("../utils/internal").createDependsOnHelpers;
+    const tryGetStackInfo = require("../utils/internal").tryGetStackInfo;
+
+    if (!stackInfo) {
+        stackInfo = tryGetStackInfo();
+    }
 
     const {
         addItem
@@ -113,5 +181,64 @@ export function functionDependsOn(
         "type": "function"
     };
 
-    addItem(newFunctionItem);
+    addItem({
+        "existsIn": stackInfo ?? null,
+        "item": newFunctionItem
+    });
+}
+
+/**
+ * Adds dependency information for a module.
+ *
+ * @example
+ * ```
+ * import {
+ *   moduleDependsOn,
+ *   getDependencies
+ * } from "@egomobile/documentation"
+ *
+ * moduleDependsOn(
+ *   require.main,
+ *   {
+ *     // your information here...
+ *   }
+ * )
+ *
+ * console.log(
+ *   getDependencies()
+ * )
+ * ```
+ *
+ * @param {any} module The module.
+ * @param {IDependencyInformation|DependencyInfoResolver} infoOrResolver The dependency information or the function that resolves it.
+ * @param {Nilable<DependenciesArg>} [dependenciesOrResolver] The custom collection for the dependency info items or the function that resolves it.
+ * @param {Nilable<IStackInfo|false>} [stackInfo] Custom stack information.
+ */
+export function moduleDependsOn(
+    module: any,
+    infoOrResolver: IDependencyInformation | DependencyInfoResolver,
+    dependenciesOrResolver?: Nilable<DependencyInfoCollectionArg>,
+    stackInfo?: Nilable<IStackInfo | false>
+) {
+    const createDependsOnHelpers: CreateDependsOnHelpersFunc =
+        require("../utils/internal").createDependsOnHelpers;
+    const tryGetStackInfo = require("../utils/internal").tryGetStackInfo;
+
+    if (!stackInfo) {
+        stackInfo = tryGetStackInfo();
+    }
+
+    const {
+        addItem
+    } = createDependsOnHelpers(infoOrResolver, dependenciesOrResolver);
+
+    const newModuleItem: IModuleDependencyItem = {
+        module,
+        "type": "module"
+    };
+
+    addItem({
+        "existsIn": stackInfo ?? null,
+        "item": newModuleItem
+    });
 }
diff --git a/src/types/dependencies.ts b/src/types/dependencies.ts
@@ -13,7 +13,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with this program. If not, see <http://www.gnu.org/licenses/>.
 
-import type { IWithClassNameProp, IWithClassOrInstanceProp, IWithEffectsProps, IWithIsStaticProp, IWithReferencesProp, IWithRemarksProp, IWithTypeProp } from ".";
+import type { IStackInfo, IWithClassNameProp, IWithClassOrInstanceProp, IWithEffectsProps, IWithIsStaticProp, IWithReferencesProp, IWithRemarksProp, IWithTypeProp } from ".";
 import type { ClassPropKey, Collection, Constructor, Nilable, Nullable, Optional, ReferenceValue } from "./internal";
 
 /**
@@ -48,6 +48,7 @@ export type DependencyItem =
     IClassDependencyItem |
     IFunctionDependencyItem |
     IMethodDependencyItem |
+    IModuleDependencyItem |
     IParameterDependencyItem |
     IPropertyDependencyItem;
 
@@ -60,6 +61,13 @@ export type DependencyItemCollectionResolver = () => Collection<DependencyItemWi
  * An extension of `DependencyItem`.
  */
 export type DependencyItemWithInfo = DependencyItem & {
+    /**
+     * Information about the underlying file, if available.
+     *
+     * While `null` means that there is no information, does `false` indicate that detection of this
+     * information failed.
+     */
+    existsIn: Nullable<IStackInfo | false>;
     /**
      * The underlying information.
      */
@@ -172,6 +180,20 @@ export interface IMethodDependencyItem extends IDependencyItem, Partial<IWithCla
     type: "method";
 }
 
+/**
+ * A `IDependencyItem` with information about a module and its dependencies.
+ */
+export interface IModuleDependencyItem extends IDependencyItem {
+    /**
+     * The module.
+     */
+    module: any;
+    /**
+     * The type.
+     */
+    type: "module";
+}
+
 /**
  * A `IDependencyItem` with information about a paremeter of a class method and its dependencies.
  */
@@ -222,6 +244,10 @@ export interface ISerializableClassDependencyItemWithInfo extends ISerializableD
  * A serizable version of an `IDependencyItem`.
  */
 export interface ISerializableDependencyItemWithInfo {
+    /**
+     * Information about the origin.
+     */
+    existsIn: Nullable<IStackInfo>;
     /**
      * The underlying information.
      */
@@ -256,6 +282,20 @@ export interface ISerializableMethodDependencyItemWithInfo extends ISerializable
     type: "method";
 }
 
+/**
+ * A serizable version of an `IModuleDependencyItem`.
+ */
+export interface ISerializableModuleDependencyItemWithInfo extends ISerializableDependencyItemWithInfo {
+    /**
+     * The name/path of the module.
+     */
+    name: string;
+    /**
+     * The type.
+     */
+    type: "module";
+}
+
 /**
  * A serizable version of an `IParameterDependencyItem`.
  */
@@ -295,5 +335,6 @@ export type SerializableDependencyItem =
     ISerializableClassDependencyItemWithInfo |
     ISerializableFunctionDependencyItemWithInfo |
     ISerializableMethodDependencyItemWithInfo |
+    ISerializableModuleDependencyItemWithInfo |
     ISerializableParameterDependencyItemWithInfo |
     ISerializablePropertyDependencyItemWithInfo;