Skip to content

Latest commit

 

History

History
145 lines (98 loc) · 7.35 KB

README.md

File metadata and controls

145 lines (98 loc) · 7.35 KB
Raw

Import Manager

License npm

This is the outsourced home of the underlying module for the rollup plugin: rollup-plugin-import-manager. To have the ability to analyze and modify JavaScript source code for import statements (cjs/es6/dynamic) without having to deal with rollup or rollup dependencies, the source code for the ImportManager class itself has its own repository. It can be downloaded and used independently from the rollup plugin and or a building process.

Install

Using npm:

npm install import-manager

How it works

ImportManager analyzes a given source code for import statements. Those are collected (in the imports object) as so called unit objects, on which the user can interact with. Also the creation of new units → import statements is possible.

Usage

Importing

import ImportManager from "import-manager"

Initializing

const manager = new ImportManager(<sourceCodeAsString>, <filename>)

constructor(source, filename, warnSpamProtection=new Set(), warnings=true, pluginInstance=null)

  • source - The unmodified source code.
  • filename (optional) - The path/name of the input file (used for hash generation only).
  • warnSpamProtection (empty Set() by default) - A Set which contains all previously printed warning hashes.
  • warnings (default true) - Pass false to suppress warning messages.
  • pluginInstance (optional) - Rollup plugin instance if used as a plugin.

imports [object]

this.imports contains all units (if analyze was called) which are objects for every import statement. It has three sub-objects for the import statement types:

  • cjs
  • dynamic
  • es6

Methods

Global Methods

Methods, callable from manager instance.

analyze()

Analyzes the source and stores all import statements as unit objects in the imports object.

selectModByName(name, type, allowNull, rawName=false)

Searches this.imports for the given module name (String|RegExp). If type is provided (cjs/dynamic/es6), it only searches for the module in that category. If allowNull is set to false the module must be found or a MatchError is thrown.
By setting rawName to true the name is searched in the whole raw module-name string. For the statement import foo from "/path/to/bar.js" the module name will be bar.js while the raw name is "/path/to/bar.js". It is therefore possible to search for the whole path if it is necessary.

selectModById(id, allowNull)

Searches this.imports for the given module id. If allowNull false the module must be found or a MatchError is thrown.

selectModByHash(hash, allowNull)

Searches this.imports for the given module hash. If allowNull false the module must be found or a MatchError is thrown.

makeCJSStatement(module, declarator, varname)

Generates a CJS Import Statement String from the module, declarator (const/let/var/global) and the varname.
<declarator> <varname> = require(<module>)

makeDynamicStatement(module, declarator, varname)

Generates a Dynamic Import Statement String including with a await call from the module, declarator (const/let/var/global) and the varname.
<declarator> <varname> = await import(<module>)

makeES6Statement(module, defaultMembers, members)

Generates an ES6 Import Statement String from the module and defaultMember and/or members if provided.
import <defaultMembers>, { <members> } from <module>

insertStatement(statement, pos, type)

Inserts an import statement to the position top of the file or the bottom which is after the last found import statement.

insertAtUnit(unit, mode, statement)

Inserts an import statement at a given unit-object. There are three different modes available:

  • append - statement gets inserted after the given unit
  • prepend - statement gets inserted before the given unit
  • replace - statement replaces the given unit
logUnits()

Debugging method to stop the building process to list all import units with its id, hash and module.

logUnitObjects()

Debugging method to stop the building process to list the complete import object with all its units, which is much more verbose than logUnits.

remove(unit)

Removes a unit from the code instance.

commitChanges(unit)

All manipulation done via a unit method is made on the code slice of the unit. This methods finally writes it to the main code instance.

Unit Methods

Methods callable from a unit object.

renameModule(name, modType)

Changes the name -> module (path). modType can either be "string" which adds quotation marks around name or "raw", which doesn't, and can be used to pass variables if valid for the import type.

Name can also be a function which passes the original raw module-name (including quotes if present) as a first parameter and must return a raw module name as a string. (eg. rawName => rawName.replace("foo", "bar"))

addDefaultMembers(names)

names is an array of strings (even for the most common case of a single member) of default members to add to the unit. [es6 only]

addMembers(names)

names is an array of strings of members to add to the unit. [es6 only]

removeMember(memberType, name)

Removes a singular defaultMember/member (distinguished by memberType) with the specified name. [es6 only]

removeMembers(membersType)

Removes all defaultMember(s) or member(s) (distinguished by memberType). [es6 only]

renameMember(memberType, name, newName, keepAlias)

Renames a singular member of memberType defaultMember/member matching the given name to a newName. It is possible to keepAlias if it should not be changed. [es6 only]

setAlias(memberType, name, set)

Sets a alias of memberType defaultMember/member of the given member name. You can either set (pass a string) a new name or don't define set to delete the alias. [es6 only]

makeUntraceable()

Method to call after a unit was completely removed or replaced, to prevent matching it again afterwards.

log()

Debugging method to stop the building process and list the unit properties.

updateUnit()

If multiple changes should be performed on a es6 unit, this method should be called after a change. If called the unit gets generated again with the updated code.

Errors

MatchError

Extends the generic JavaScript Error. An error to inform, that it is not possible to select a specific unit.

DebuggingError

Extends the generic JavaScript Error. An error to deliberately abort the building process for retrieving information about the imports/units.

License

MIT

Copyright (c) 2022-2023, UmamiAppearance