feat: serializable types and optional key for IDependencyInformation

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log (@egomobile/documentation)
 
+## 0.3.0
+
+- implement serializable types and `serializeDependencies()` utility function
+- add `classOrInstance` prop to `IMethodDependencyItem`, `IParameterDependencyItem` and `IPropertyDependencyItem`
+- add optional `key` to `IDependencyInformation`
+
 ## 0.2.0
 
 - add `references` props to `IDependencyInformation`, `IDependencyInformationEntity` and `IDependencyInformationEntityAttribute`

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@egomobile/documentation",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Tools for documenting (TypeScript) code.",
     "main": "lib/index.js",
     "engines": {

src/decorators/DependsOn.ts

@@ -15,7 +15,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 { ClassPropKey, Collection, Constructor, IArrayLike, Nilable, Optional, ReferenceValue } from "../types/internal";
+import type { ClassOrInstance, ClassPropKey, Collection, Constructor, IArrayLike, Nilable, Optional, ReferenceValue } from "../types/internal";
 import { isCollection } from "../utils/internal";
 
 /**
@@ -101,6 +101,10 @@ export interface IDependencyInformation {
      * Optional entities for this app.
      */
     entities?: Nilable<DependencyInformationEntities>;
+    /**
+     * Optional unique key. Value should be handled case-insensitive.
+     */
+    key?: Nilable<ReferenceValue>;
     /**
      * An optional list of references. Should be handled as URIs.
      */
@@ -209,6 +213,10 @@ export interface IDependencyItem {
  * A `IDependencyItem` with information about a class method and its dependencies.
  */
 export interface IMethodDependencyItem extends IDependencyItem {
+    /**
+     * The underlying class or constructor.
+     */
+    classOrInstance: ClassOrInstance<any>;
     /**
      * The key / name.
      */
@@ -224,13 +232,17 @@ export interface IMethodDependencyItem extends IDependencyItem {
  */
 export interface IParameterDependencyItem extends IDependencyItem {
     /**
-     * The key / name, if available.
+     * The underlying class or constructor.
      */
-    key?: Optional<ClassPropKey>;
+    classOrInstance: ClassOrInstance<any>;
     /**
      * The zero-based index inside the method.
      */
     index: number;
+    /**
+     * The key / name, if available.
+     */
+    key?: Optional<ClassPropKey>;
     /**
      * The type.
      */
@@ -241,6 +253,10 @@ export interface IParameterDependencyItem extends IDependencyItem {
  * A `IDependencyItem` with information about a class property and its dependencies.
  */
 export interface IPropertyDependencyItem extends IDependencyItem {
+    /**
+     * The underlying class or constructor.
+     */
+    classOrInstance: ClassOrInstance<any>;
     /**
      * The key / name.
      */
@@ -453,45 +469,79 @@ export function DependsOn(
     return (...args: any[]) => {
         const target: any = args[0];
 
-        if (typeof target === "function") {
-            const newClassItem: IClassDependencyItem = {
-                "constructor": target,
-                "type": "class"
+        const addAsMethod = () => {
+            const propertyKey: Optional<ClassPropKey> = args[1];
+
+            const newMethodItem: IMethodDependencyItem = {
+                "classOrInstance": target,
+                "key": propertyKey as ClassPropKey,
+                "type": "method"
             };
 
-            addItem(newClassItem);
-        }
-        else {
+            addItem(newMethodItem);
+        };
+
+        const addAsParameter = () => {
+            const descriptorOrIndex: Optional<TypedPropertyDescriptor<any> | number> = args[2];
+            const propertyKey: Optional<ClassPropKey> = args[1];
+
+            const newParameterItem: IParameterDependencyItem = {
+                "classOrInstance": target,
+                "index": descriptorOrIndex as number,
+                "key": propertyKey,
+                "type": "parameter"
+            };
+
+            addItem(newParameterItem);
+        };
+
+        const addAsProperty = () => {
             const propertyKey: Optional<ClassPropKey> = args[1];
+
+            const newPropertyItem: IPropertyDependencyItem = {
+                "classOrInstance": target,
+                "key": propertyKey as ClassPropKey,
+                "type": "property"
+            };
+
+            addItem(newPropertyItem);
+        };
+
+        const addWith3Args = () => {
             const descriptorOrIndex: Optional<TypedPropertyDescriptor<any> | number> = args[2];
 
             if (typeof descriptorOrIndex === "undefined") {
-                const newPropertyItem: IPropertyDependencyItem = {
-                    "key": propertyKey as ClassPropKey,
-                    "type": "property"
-                };
-
-                addItem(newPropertyItem);
+                addAsProperty();
+            }
+            else if (typeof descriptorOrIndex === "number") {
+                addAsParameter();
             }
             else {
-                if (typeof descriptorOrIndex === "number") {
-                    const newParameterItem: IParameterDependencyItem = {
-                        "index": descriptorOrIndex as number,
-                        "key": propertyKey,
-                        "type": "parameter"
-                    };
-
-                    addItem(newParameterItem);
-                }
-                else {
-                    const newMethodItem: IMethodDependencyItem = {
-                        "key": propertyKey as ClassPropKey,
-                        "type": "method"
-                    };
-
-                    addItem(newMethodItem);
-                }
+                addAsMethod();
             }
+        };
+
+        if (typeof target === "function") {
+            if (args.length === 3) {
+                // static member
+
+                addWith3Args();
+            }
+            else if (args.length === 1) {
+                // class
+
+                const newClassItem: IClassDependencyItem = {
+                    "constructor": target,
+                    "type": "class"
+                };
+
+                addItem(newClassItem);
+            }
+        }
+        else {
+            // instance member
+
+            addWith3Args();
         }
     };
 }

src/index.ts

@@ -14,3 +14,5 @@
 // along with this program. If not, see <http://www.gnu.org/licenses/>.
 
 export * from "./decorators";
+export * from "./types";
+export * from "./utils";

src/types/index.ts

@@ -0,0 +1,116 @@
+// This file is part of the @egomobile/documentation distribution.
+// Copyright (c) Next.e.GO Mobile SE, Aachen, Germany (https://e-go-mobile.com/)
+//
+// @egomobile/documentation is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// @egomobile/documentation is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// Lesser General Public License for more details.
+//
+// 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 } from "../decorators";
+import type { Nullable } from "./internal";
+
+/**
+ * A serizable version of an `IClassDependencyItem`.
+ */
+export interface ISerializableClassDependencyItemWithInfo extends ISerializableDependencyItemWithInfo {
+    /**
+     * The name of the class.
+     */
+    name: string;
+    /**
+     * The type
+     */
+    type: "class";
+}
+
+/**
+ * A serizable version of an `IDependencyItem`.
+ */
+export interface ISerializableDependencyItemWithInfo {
+    /**
+     * The underlying information.
+     */
+    info: IDependencyInformation;
+}
+
+/**
+ * A serizable version of an `IMethodDependencyItem`.
+ */
+export interface ISerializableMethodDependencyItemWithInfo extends ISerializableDependencyItemWithInfo, IWithClassNameProp, IWithIsStaticProp {
+    /**
+     * The name of the method.
+     */
+    name: string;
+    /**
+     * The type.
+     */
+    type: "method";
+}
+
+/**
+ * A serizable version of an `IParameterDependencyItem`.
+ */
+export interface ISerializableParameterDependencyItemWithInfo extends ISerializableDependencyItemWithInfo, IWithClassNameProp, IWithIsStaticProp {
+    /**
+     * The zero-based index inside the method.
+     */
+    index: number;
+    /**
+     * The name, if available.
+     */
+    name: Nullable<string>;
+    /**
+     * The type.
+     */
+    type: "parameter";
+}
+
+/**
+ * A serizable version of an `IPropertyDependencyItem`.
+ */
+export interface ISerializablePropertyDependencyItemWithInfo extends ISerializableDependencyItemWithInfo, IWithClassNameProp, IWithIsStaticProp {
+    /**
+     * The name of the property.
+     */
+    name: string;
+    /**
+     * The type.
+     */
+    type: "property";
+}
+
+/**
+ * An object with an `className` property.
+ */
+export interface IWithClassNameProp {
+    /**
+     * The name of the underlying class, if available.
+     */
+    className: Nullable<string>;
+}
+
+/**
+ * An object with an `isStatic` property.
+ */
+export interface IWithIsStaticProp {
+    /**
+     * Is underlying type static or not.
+     */
+    isStatic: boolean;
+}
+
+/**
+ * An serializable dependency info item.
+ */
+export type SerializableDependencyItem =
+    ISerializableClassDependencyItemWithInfo |
+    ISerializableMethodDependencyItemWithInfo |
+    ISerializableParameterDependencyItemWithInfo |
+    ISerializablePropertyDependencyItemWithInfo;

src/types/internal.ts

@@ -13,6 +13,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/>.
 
+export type ClassOrInstance<T extends any = Object> = T | Constructor<T>;
+
 export type ClassPropKey = string | symbol;
 
 export type Collection<T extends any = any> =