@komaci/common-shared 240.1.3

package/build/types.d.ts

@@ -0,0 +1,193 @@
+import { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { PrimitiveValue, PropertyReference, UnresolvedValue, ImportReference as KomaciDocImportReference, Binding } from '@komaci/types';
+/**
+ * @typedef ClassPropertyInfo is an object that holds information about a class property
+ * @property {t.ClassProperty | t.ClassMethod | NodePath<t.ClassProperty | t.ClassMethod>} classProp is the class property babel object.
+ * @property {string} classPropId is the id of the class property.
+ * @property {string} decoratorType is the type of decorate. Ex: api, track, wire
+ * @property {boolean} isDecorated whether this class property is decorated or not
+ * @property {boolean} hasInitialValue whether this class property has an initial value
+ */
+export declare type ClassPropertyInfo = {
+    classProp: t.ClassProperty | t.ClassMethod | NodePath<t.ClassProperty | t.ClassMethod>;
+    classPropId: string;
+    decoratorType?: string;
+    isDecorated: boolean;
+    hasInitialValue: boolean;
+};
+/**
+ * @typedef ValidGetterContext is an object that holds information about the member varaibles within a getter function.
+ * @property {NodePath<t.ClassMethod>} getter is the babel object for the getter method node.
+ * @property {Array<string>} memberUsage is an array of member variable names that are within the getter.
+ * @property {number} f_index is the index at which this getter was added to the functions array in the Komaci document.
+ */
+export declare type ValidGetterContext = {
+    getter: NodePath<t.ClassMethod>;
+    memberUsage: Array<string>;
+    generatedName: string;
+    f_index?: number;
+};
+/**
+ * @typedef ValidTemplateContext is an object that holds information about the member varaibles within a template.
+ * @property {NodePath<t.ClassProperty>} template is the babel object for the getter method node.
+ * @property {Array<string>} memberUsage is an array of member variable names that are within the template.
+ * @property {string} generatedName name used as function name in the resolvable module
+ * @property {number} f_index is the index at which this template was added to the functions array in the Komaci document.
+ */
+export declare type ValidTemplateContext = {
+    template: NodePath<t.ClassProperty>;
+    memberUsage: Array<string>;
+    generatedName: string;
+    f_index?: number;
+};
+/**
+ * @typedef ImportDeclarationInfo is an object that holds information about the import declarations
+ * @property {string} identifierName is the name of the imported resource.
+ * @property {string} namespace Full import source path
+ * @property {boolean} isSupported a boolean field to determine if an import is supported or not.
+ * @property {boolean} isDefault a boolean field to determine if an import is the default import.
+ * @property {boolean} isNamespaceSpecifier a boolean field to determine if an import is a namespace import.
+ * @property {string} trueName sometimes imports are renamed so we maintain their true name for later processing
+ */
+export declare type ImportDeclarationInfo = {
+    identifierName: string;
+    namespace: string;
+    isSupported: boolean;
+    isDefault: boolean;
+    isNamespaceSpecifier: boolean;
+    trueName?: string;
+};
+/**
+ * @typedef AstContext is an object that holds meta data information about the ast.
+ * @property {Map<string, ImportDeclarationInfo>} importDeclarations a collection of importDeclarationInfo
+ * @property {string[]} moduleFunctions is a collection of function names that are defined on the module level.
+ * @property {string[]} moduleVariables is a collection of variable names that are defined on the module level.
+ * @property {string[]} classFunctions is a collection of functino names that are defined on the class level.
+ * @property {string[]} classProperties is a collection of class properties.
+ */
+export declare type AstContext = {
+    importDeclarations: Map<string, ImportDeclarationInfo>;
+    moduleFunctions: string[];
+    moduleVariables: string[];
+    classFunctions: string[];
+    classProperties: ClassPropertyInfo[];
+};
+/**
+ * Contextual info about all the imports from a specific resource for use in module composition
+ */
+export declare type ImportDetail = {
+    /** The path where the import comes from i.e. 'lwc' or 'lds/getRecord' */
+    resourceName: string;
+    /** The names of the specific things imported */
+    names: Set<string>;
+    /** If this import is a namespace */
+    isNamespaceSpecifier: boolean;
+    /** If this import contains a default specifier */
+    isDefaultSpecifier: boolean;
+    /** If this import is from a supported namespace */
+    isSupported: boolean;
+};
+/** Mapping of resources to contextual info about themselves */
+export declare type ConsumedImports = Map<string, ImportDetail>;
+/** Mapping of specific imports to their general metadata info */
+export declare type ImportDeclarations = Map<string, ImportDeclarationInfo>;
+/**
+ * A stateful object to populate across getters for how they consume high level things. like imports.
+ *
+ * @property {Map} consumedImports all of the imports that getters use. This is uniquely data not retrievable by komaci document.
+ */
+export declare type ModuleLevelConsumption = {
+    consumedImports: ConsumedImports;
+};
+/**
+ * Metadata about specific things a getter consumed. for later processing
+ */
+export declare type ImplicitConsumption = {
+    identifiers: string[];
+};
+/**
+ * Possbile types of properties we can encounter in a LWC
+ */
+export declare enum PropertyTypes {
+    WIRE = "wire",
+    GETTER = "getter",
+    INTERNAL = "internal",
+    PUBLIC = "api",
+    IMPORT_REFERENCE = "importReference",
+    TEMPLATE_STRING = "templateString"
+}
+/**
+ * Contextual information about a property and who consumes it
+ */
+export declare type ClassPropertyContext = BasePropertyContext | WirePropertyContext | ImportPropertyContext;
+/**
+ * Base type for property context
+ */
+export declare type BasePropertyContext = {
+    /** Type of property */
+    type: PropertyTypes;
+    /** If this property is used in priming through wires, compositions or implicitly through a getter */
+    usedInPriming: boolean;
+};
+/**
+ * Added metadata specifically for wire properties
+ */
+export declare type WirePropertyContext = BasePropertyContext & {
+    /** type explicitly set to wire */
+    type: PropertyTypes.WIRE;
+    /** reference to import data */
+    wire: ImportMetadata;
+};
+/**
+ * Added metadata specifically for properties that get values from imports
+ */
+export declare type ImportPropertyContext = BasePropertyContext & {
+    /** reference to import data */
+    imports: Record<string, ImportMetadata>;
+};
+/**
+ * Basic details about an Import
+ */
+export declare type ImportMetadata = {
+    /** The name of the import as defined in the import object on komaci doc */
+    name: string;
+    /** The name of the import namespace as defined in the import object on komaci doc */
+    resourceName: string;
+    /** The referential id for this import. i.e. 0/names/0 */
+    komaciDocImportRef: string;
+};
+/**
+ * Map for all class properties and their basic, KomaciDoc analyzable metadata.
+ *
+ * For getters we can update the needful properties to be of type getter.
+ * Since we don't know from the KomaciDoc if it is a geter or not
+ */
+export declare type ClassPropertyContexts = Map<string, ClassPropertyContext>;
+/**
+ * InputTraversalCallback type
+ * This is the signature of Input traversal callback methods, which are triggered
+ * whenever a certain real value, as determined by the method, is encountered
+ */
+export declare type InputTraversalCallback = (
+/** The real value for which the callback is searching */
+res: PropertyReference | PrimitiveValue | KomaciDocImportReference | UnresolvedValue | Binding, 
+/** The key to which the value sought out is sometimes mapped */
+key?: string) => boolean;
+/**
+ *  NodePaths from babel for the different complex types of class properties.
+ *
+ *  We collect these so in the future we can do traversals on their sub trees.
+ */
+export declare type ClassPropertyNodes = {
+    /** nodes representative of getter functions */
+    getters: NodePath<t.ClassMethod>[];
+    /** nodes representative of Template strings */
+    templateStrings: NodePath<t.ClassProperty>[];
+};
+/** Contextual info about class and overarching module */
+export declare type ModuleContext = {
+    astContext: AstContext;
+    isExternal: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/build/types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropertyTypes = void 0;
+/**
+ * Possbile types of properties we can encounter in a LWC
+ */
+var PropertyTypes;
+(function (PropertyTypes) {
+    PropertyTypes["WIRE"] = "wire";
+    PropertyTypes["GETTER"] = "getter";
+    PropertyTypes["INTERNAL"] = "internal";
+    PropertyTypes["PUBLIC"] = "api";
+    PropertyTypes["IMPORT_REFERENCE"] = "importReference";
+    PropertyTypes["TEMPLATE_STRING"] = "templateString";
+})(PropertyTypes = exports.PropertyTypes || (exports.PropertyTypes = {}));
+//# sourceMappingURL=types.js.map

package/build/utils.d.ts

@@ -0,0 +1,153 @@
+import * as t from '@babel/types';
+import { NodePath } from '@babel/core';
+import { AstContext, ClassPropertyContext, ClassPropertyContexts, ClassPropertyInfo, ClassPropertyNodes, ConsumedImports, ImplicitConsumption, ImportDeclarationInfo, ImportDeclarations, ModuleLevelConsumption } from './types';
+export declare const LIGHTNING_NS = "lightning";
+export declare const FORCE_NS = "force";
+export declare const ONE_NS = "one";
+/**
+ * collect node paths for different pieces of a given class so we can more effectively traverse them in the future
+ *
+ * we must do an init traversal to take nodes and turn them into nodepaths, which have context about their position in tree
+ * we need this info so we can do sub tree traversals later.
+ * @param ast babel abstract syntax tree
+ */
+export declare function getPropertyMetadataFromAst(ast: t.File): ClassPropertyNodes;
+/**
+ * Given the AST of an entire JS source file, this method looks for class member properties.
+ * If there is no default export in the AST, no class properties will be returned (empty array is returned).
+ * @param astRoot AST representing an entire Program, as a @babel/types File object
+ * @returns Array of NodePath<ClassProperty> representing the @babel NodePaths for all class member
+ *          properties, if any exist. Otherwise, returns an empty array.
+ */
+export declare function getClassProperties(astRoot: t.File): t.ClassProperty[];
+/**
+ * Utility method that takes in an @babel/types ClassProperty array, and returns an array of ClassPropertyInfo
+ * objects containing information about each ClassProperty from the input array.
+ * @param classProperties
+ * @returns Array of ClassPropertyInfo, where each element corresponds to the input ClassProperty array.
+ */
+export declare function getClassPropertyInfos(classProperties?: Array<t.ClassProperty | t.ClassMethod>): ClassPropertyInfo[];
+/**
+ * Given a valid functional node (tempalte string or getter function), collect information that we may not have been able to collect via KomaciDocument
+ * and return a list of class member variables that are properly used in the method body.
+ * "properly" = i.e. used in the right-hand side of a member expression.
+ * @param getter NodePath<ClassMethod | Class Property> path that represents class member-level getter method or template string
+ *               e.g. "get myId() { return '187291110cd3a'; }"
+ * @param classPropInfos ClassPropertyInfo[] that contains all of the class-level properties.
+ * @param importDeclarations Map<string, ImporDeclarationInfo> which contains metadata for all import statements
+ *                           that currently exist. Does not contain state as to whether that import is being used.
+ * @param moduleLevelConsumption ModuleLevelConsumption. Contains a ConsumedImports which in turn contains a Map<string, ImportDetail>
+ *                               which in turn holds state as tp which imports are currently being used
+ * @returns ImplicitConsumption, which contains an array representing the properly-used member variables.
+ *          Returns ImplicitConsumption with an empty array if none were found.
+ */
+export declare function implicitConsumptionMetadata(node: NodePath<t.ClassMethod | t.ClassProperty>, classPropInfos: ClassPropertyInfo[], importDeclarations: Map<string, ImportDeclarationInfo>, // import metadata
+moduleLevelConsumption: ModuleLevelConsumption): ImplicitConsumption;
+export declare function getMemberVarsFromGetter(path: NodePath<t.MemberExpression>, identifiers: Set<string>): void;
+/**
+ * Collect metadata about all the imports consumed for an identifier in a getter
+ * @param path NodePath of the current Identifier in the getter
+ * @param classPropInfos Array of ClassPropertyInfo objects that have all of the information
+ *        related to all class properties in the class.
+ * @param importDeclarations Metadata about all the imports
+ * @param consumedImports The map to add info to about this identifier, whether it is an import that is being used
+ *                        in the getter, or if it is assigned an import being used in the getter.
+ */
+export declare function collectImportUsage(path: NodePath<t.Identifier>, classPropInfos: ClassPropertyInfo[], importDeclarations: ImportDeclarations, consumedImports: ConsumedImports): void;
+/**
+ * Some children of nodes can be a direct identifier or a string literal. helper helps do
+ * this consistant dance of getting the value from either
+ * @param node Node to ge value of
+ * @returns value
+ */
+export declare function getFromIdentifierOrStringLiteral(node: t.Identifier | t.StringLiteral): string;
+/**
+ * Function for getting an array of supported namesapce references.
+ * @param astRoot the root of the ast
+ * @returns an Array of supported namespace references.
+ */
+export declare function getAllImportReferences(astRoot: t.File): Map<string, ImportDeclarationInfo>;
+/**
+ * Function to get an array of function names that are defined at the module level.
+ * @returns an array of function names that are defined at the module level.
+ */
+export declare function getAllModuleFunctions(astRoot: t.File): string[];
+/**
+ * Function that returns an array of variable names that are defined at the module level.
+ * @param astRoot the root ast node.
+ * @returns an array of variable names that are defined at the module level.
+ */
+export declare function getAllModuleVaraibles(astRoot: t.File): string[];
+/**
+ * Function to get an array of function names that are defined on the default exports class.
+ * @returns an array of function names that are defined on the class.
+ */
+export declare function getAllClassMethods(astRoot: t.File): string[];
+/**
+ * Function to get an AstContext object for a given ast.
+ * @param ast the ast.
+ * @returns a context object containing meta data about the ast.
+ */
+export declare function getAstContextObject(ast: t.File): AstContext;
+/** Determines if the module (i.e LWC Component) was written by an external user. If the namespace of the module
+ * exactly matches one of 'lightning', 'force', or 'one', it is NOT an external component.
+ * @param namespace string namespace of the ModuleInfo to check (comes from ModuleInfo.namespace)
+ * @returns true if moduleInfo is an external module, false otherwise
+ */
+export declare function isExternalModule(namespace: string): boolean;
+/**
+ * Helper function to collect all variables declared within a getter method.
+ * @param getterMethodPath the babel path object of the getter method.
+ * @returns an array of variable names that were declared in the getter method.
+ */
+export declare function getVariablesDeclaredInGetter(getterMethodPath: NodePath<t.ClassMethod>): string[];
+/**
+ * Helper to get the name of a method
+ * @param node The method node
+ * @returns the name of the node
+ */
+export declare function getClassMethodName(node: NodePath<t.ClassMethod>): string;
+/**
+ * Check whether a property is used either directly or indirectly
+ * @param prop The prop details
+ * @returns if it is used
+ */
+export declare function isPropertyUsed(prop?: ClassPropertyContext): boolean;
+/**
+ * High level wrapper to parse getter info from a babel node before checking if it is used
+ * @param getter The getter node
+ * @param properties Metadata about class properties
+ * @returns if it is used directly
+ */
+export declare function isGetterNodeUsed(getter: NodePath<t.ClassMethod>, properties: ClassPropertyContexts): boolean;
+/**
+ * High level wrapper to parse prop info from a babel node before checking if it is used
+ * @param prop The prop babel node
+ * @param properties Metadata about class properties
+ * @returns if it is used directly
+ */
+export declare function isPropertyNodeUsed(prop: NodePath<t.ClassProperty>, properties: ClassPropertyContexts): boolean;
+/**
+ * @author xiaoxugu
+ * Helper function to collect all variables declared as alias of this.
+ * eg. const self = this, const that = this.
+ * @param getterMethodPath the babel path object of the getter method.
+ * @returns a {Set<string>} of variable names that were declared as alias of 'this'.
+ */
+export declare function getThisAliasDeclaredInGetter(getterMethodPath: NodePath<t.ClassMethod>): Set<string>;
+/**
+ * @author xiaoxugu
+ * Determines whether the passed in {Expression} is a `this` or whether it is an equivalent alias to `this`
+ * @param {Set<string>} aliases a Set<string> of variables that were assigned `this`
+ * @param {Expression | null | undefined} expr the Expression whose type is being evaluated
+ * @returns {boolean} returns true is the Expression is a `ThisExpression` or an alias to one
+ */
+export declare function isExpressionThisOrAlias(aliases: Set<string>, expr: t.Expression | null | undefined): boolean;
+/**
+ * Function to check if the id we are referecing is either declared as a class property, import reference or module variale
+ * @param astContext the ast context
+ * @param declaredGetterVars a collection of variables declared within the getter
+ * @param id the id of the member we are referencing.
+ */
+export declare function isDeclaredInAst(astContext: AstContext, declaredGetterVars: string[], id: string): boolean;
+//# sourceMappingURL=utils.d.ts.map