{ "name": "lively.modules", "version": "0.5.19", "main": "dist/lively.modules.js", "repository": { "type": "git", "url": "https://github.com/LivelyKernel/lively.modules" }, "author": { "name": "Robert Krahn", "email": "robert.krahn@gmail.com" }, "license": "MIT", "scripts": { "test": "node_modules/mocha-es6/bin/mocha-es6.js tests/*-test.js", "build": "node tools/build.js" }, "systemjs": { "main": "./index.js", "map": { "lively.modules": ".", "fs": { "node": "@node/fs", "~node": "@empty" } } }, "lively": { "main": "index.js", "packageMap": { "lively.lang": "./node_modules/lively.lang", "lively.ast": "./node_modules/lively.ast", "lively.vm": "./node_modules/lively.vm", "mocha-es6": "./node_modules/mocha-es6" } }, "dependencies": { "lively.ast": "^0.7.25", "lively.vm": "^0.7.10", "lively.lang": "^0.7.0", "systemjs": "^0.19.29", "systemjs-plugin-babel": "0.0.12" }, "devDependencies": { "babel-core": "^6.9.1", "babel-plugin-syntax-object-rest-spread": "^6.8.0", "babel-plugin-transform-async-to-generator": "^6.8.0", "babel-plugin-transform-object-rest-spread": "^6.8.0", "babel-preset-es2015-rollup": "^1.1.1", "babel-regenerator-runtime": "^6.5.0", "doc-comments": "^0.1.4", "mocha-es6": "^0.3.1", "rollup": "^0.33.0", "rollup-plugin-babel": "^2.5.1" }, "readme": "# lively.modules [![Build Status](https://travis-ci.org/LivelyKernel/lively.modules.svg)](https://travis-ci.org/LivelyKernel/lively.modules)\n\nJavaScript package and module system for interactive development.\n\n### Module and package system\n\n![](http://lively-web.org/users/robertkrahn/uploads/Screen_Shot_2016-03-26_at_8.30.54_PM.png)\n\n### Live and interactive devlopment\n\n![](http://lively-web.org/users/robertkrahn/uploads/videos/async-await-eval.gif)\n\n## Goals\n\nlively.modules provides a framework for loading, defining and interactively\nmodifying *JavaScript modules*. A module is an entity containing JavaScript\nsource code that adheres to the definition of the\n[ECMAScript Language Specification](https://tc39.github.io/ecma262/#sec-modules).\n\nFor an intro to the topic see [ES6 In Depth: Modules at mozilla.org](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/)\n\nIts main purpose is to\n\n- Provide an interface to load modules and groups of modules (packages)\n- Provide an interface to access and modify the runtime state of a module, i.e. its\n - dependencies (modules imported and modules that import it)\n - imported and exported values\n - source code\n - internal definitions\n- Provide a user friendly and practical implementation of how imported modules\n are resolved *.\n- For the purpose of grouping modules together and providing a method for\n module lookup introduce a lightweight concept of a *package*.\n\n\n[*](#resolve-module-note) The ES specification explicitly\n[leaves the semantics for \"HostResolveImportedModule\" open to module\nimplementations](https://tc39.github.io/ecma262/#sec-hostresolveimportedmodule)\n\nFor more please see [doc/rationale.md](doc/rationale.md).\n\n\n## Usage\n\n\nTo load lively.modules you can use the pre-build\n`dist/lively.modules-with-lively.vm.js` file. Once that happens the\n`lively.modules` global will provide an interface for loading packages,\nmodifying modules, evaluating source code in module contexts etc.\n\nSo on a webpage you would typically link via\n\n```html\n\n```\n\nSee the examples in\n[lively-system-examples](https://github.com/LivelyKernel/lively-system-examples)\nfor more details.\n\n\n## API\n\n\n\n\n\n\n\n### [main interface](index.js)\n\n\n\n### `lively.modules.importPackage(packageName)`\n\nTo load a project into your runtime you will typically use\n`lively.modules.importPackage('some-package-name')`. `'some-package-name'`\nshould resolve to a directory with a JSON package config file (typically\npackage.json) that at least defines a `name` field. The package will be\nimported, i.e. the main module of the package will be loaded via\n`lively.modules.System.import('some-package-name/index.js')`. By default the\nname of main is `'index.js'` but this can be customized via the `main` field\nof the package config file.\n\nThe result of the importPackage call is the promise for loading the main module.\n\n\n\n#### Specifics of the lively package format\n\nThe main purpose of the lively package format is to make it easy to integrate\ndependent packages in the lively.module and es6 module systems. It allows you\nto define a `\"lively\"` field in the main JSON that allows to set a separate\nmain module, a `\"packageMap\"` object that maps names that can be used in\n`import` statements to directories of sub-packages. When sub-packages are\ndiscovered while importing a package, those are recursively imported as well.\n\nHere is an example how a config inside a package.json file could look like.\n\n```json\n{\n \"name\": \"some-package\",\n \"main\": \"main-for-non-es6.js\",\n \"lively\": {\n \"main\": \"for-es6.js\",\n \"packageMap\": {\n \"dep1\": \"./node_modules/dep1\",\n \"dep2\": \"./libs/dep2\"\n }\n }\n}\n```\n\nFor more examples, see [lively.modules/package.json](https://github.com/LivelyKernel/lively.modules/package.json), or [lively.ast/package.json](https://github.com/LivelyKernel/lively.ast/package.json).\n\n\n\n### `lively.modules.System`\n\nThe main lively.modules interface provides access to a System loader object\n(currently from the [SystemJS library](https://github.com/systemjs/systemjs)\nthat has some improvements added, e.g. the name normalization respects the\nlively package conventions, translate is used to instrument code by\ndefault, etc.\n\nBy default the loader instance is the same as the global loader (e.g.\nwindow.System). Note: *The System instance can be easily changed* to support\nmultiple, isolated environnments.\n\nExample:\n\n```js\nvar testSystem = lively.modules.getSystem(\"my-test-system\");\nlively.modules.changeSystem(testSystem, true); // true: make the System global\nSystem.import(\"some-module\"); // uses the new System loader\n```\n\nNow all state (what modules are loaded, their metadata, etc) are stored in\n`testSystem`. Changing to another System allows to define different name\nresolution approach etc.\n\nSide note: Since all System related implementation functions defined in the\nmodules in src/ will take a System loader object as first parameter, the\nimplementation is loader independent.\n\n\n\n### Loader state / module state\n\n- `lively.modules.loadedModules()`: Returns a list of ids of the currently loaded modules.\n\n- lively.modules.printSystemConfig(): Returns a stringified version of the [SystemJS config](https://github.com/systemjs/systemjs/blob/master/docs/config-api.md). Useful for debugging SystemJS issues\n\n#### `lively.modules.requireMap()`\n\nWill return a JS object whose keys are module ids and the corresponding\nvalues are lists of module ids of those modules that dependent on the key\nmodule (including the key module itself). I.e. the importers of that module.\n\n\n\n### instrumentation\n\nBy default lively.modules will hook into the `System.translate` process so that source code of modules get transformed to allow recording of their internal evaluation state (that is then captured in `moduleEnv`s). You can enable and disable this behavior via\n\n- `lively.modules.wrapModuleLoad()`\n- `lively.modules.unwrapModuleLoad()`\n\n\n\n### evaluation\n\n* This is handled by the [lively.vm module](https://github.com/LivelyKernel/lively.vm)!\n\n\n\n### ModuleInterface\n\n#### `lively.modules.module(moduleId)`\n\nReturns an instance of ModuleInterface with the following methods:\n\n##### `ModuleInterface>>dependents()`\n\nWhich modules (module ids) are (in)directly import module with id.\n\nLet's say you have\n\n- module1.js: `export var x = 23;`\n- module2.js: `import {x} from \"module1.js\"; export var y = x + 1;`\n- module3.js: `import {y} from \"module2.js\"; export var z = y + 1;`\n\n`module(\"module1.js\").dependents()` returns [module(\"module2\"), module(\"module3\")]\n\n##### `ModuleInterface>>requirements()`\n\nwhich modules (module ids) are (in)directly required by module with id?\n\nLet's say you have\n\n- module1: `export var x = 23;`\n- module2: `import {x} from \"module1.js\"; export var y = x + 1;`\n- module3: `import {y} from \"module2.js\"; export var z = y + 1;`\n\n`module(\"module3\").requirements()` will report [module(\"module2\"), module(\"module1\")]\n\n##### `async ModuleInterface>>changeSource(newSource, options)`\n\nTo redefine a module's source code at runtime you can use the\nchangeSource method. Given `a.js` from the previous example you can run\n`module('a.js').changeSource('var x = 24;\\nexport x;')`.\nThis will a) evaluate the changed code and b) try to modify the actual file\nbehind the module. In browser environments this is done via a `PUT` request,\nin node.js `fs.writeFile` is used.\n\n##### `async ModuleInterface>>reload(options)``\n\nWill re-import the module identified by `moduleName`. By default this will\nalso reload all direct and indirect dependencies of that module. You can\ncontrol that behavior via `options`, the default value of it is\n`{reloadDeps: true, resetEnv: true}`.\n\n##### `ModuleInterface>>unload(options)`\n\nWill remove the module from the loaded module set of lively.modules.System.\n`options` are by default `{forgetDeps: true, forgetEnv: true}`.\n\n##### `async ModuleInterface>>imports()` and `async ModuleInterface>>exports()`\n\nImport and export state. For exports this includes the local name of the\nexported variable, its export name, etc. For imports it includes the imported\nvariable name, the module from where it was imported etc.\n\nExample:\n\n```js\nawait module(\"lively.modules/index.js\").exports();\n // =>\n // [{\n // exported: \"getSystem\",\n // local: \"getSystem\",\n // fromModule: \"http://localhost:9001/node_modules/lively.modules/index.js\",\n // }, ...]\n\nawait module(\"lively.modules/index.js\").imports();\n // [{\n // fromModule: \"lively.lang\",\n // local: \"obj\",\n // localModule: \"http://localhost:9001/node_modules/lively.modules/index.js\"\n // }, {\n // fromModule: \"./src/system.js\",\n // local: \"getSystem\",\n // localModule: \"http://localhost:9001/node_modules/lively.modules/index.js\"\n // }, ...]\n // })\n```\n\n\n##### `async ModuleInterface>>source()`\n\nReturns the source code of the module.\n\n##### `async ModuleInterface>>env()`\n\nReturns the evaluation environment of the module.\n\nA \"module env\" is the object used for recording the evaluation state. Each\nmodule that is loaded with source instrumentation enabled as an according\nmoduleEnv It is populated when the module is imported and then used and\nmodified when users run evaluations using `lively.vm.runEval()` or change the module's\ncode with `ModuleInterface>>changeSource()`. You can get access to the internal module\nstate via `module(...).env().recorder` the recorder is a map of\nvariable and function names.\n\nExample: When lively.modules is bootstrapped you can access the state of its\nmain module via:\n\n```js\nvar id = System.decanonicalize(\"lively.modules/index.js\");\nObject.keys(lively.modules.moduleEnv(\"lively.modules/index.js\").recorder);\n // => [\"defaultSystem\", \"changeSystem\", \"loadedModules\", \"sourceOf\", \"moduleEnv\", ...]\nlively.modules.moduleEnv(\"lively.modules/index.js\").recorder.changeSystem\n // => function() {...} The actual object defined in the module scope\n```\n\n\n\n### hooks\n\nlively.modules provides an easy way to customize the behavior of the System\nloader object via `installHook` and `removeHook`. To extend the behavior of\nof `lively.modules.System.fetch` you can for example do\n\n```js\ninstallHook(\"fetch\", function myFetch(proceed, load) {\n if (load.name === \"my-custom-module.js\") return \"my.custom.code()\";\n return proceed(load); // default behavior\n});\n```\n\n\n\n\n\n\n\n## Development\n\nTo bootstrap lively.modules please see the example in\n[examples/bootstrap/](examples/bootstrap/). lively.modules is completely\ncapable to \"develop itself\" and was done so from the beginning :)\n\nTo build a new version yourself run `npm run build`.\n\n## LICENSE\n\n[MIT](LICENSE)\n", "readmeFilename": "README.md", "description": "JavaScript package and module system for interactive development.", "bugs": { "url": "https://github.com/LivelyKernel/lively.modules/issues" }, "_id": "lively.modules@0.5.19", "_from": "lively.modules@*" }