{"id":20044141,"url":"https://github.com/jurooravec/inject-definition","last_synced_at":"2026-04-25T22:34:19.425Z","repository":{"id":57273971,"uuid":"151013961","full_name":"JuroOravec/inject-definition","owner":"JuroOravec","description":"Inject user-defined definitions, macros, constants or other snippets to a text simply if corresponding keywords are present.","archived":false,"fork":false,"pushed_at":"2020-04-07T03:12:29.000Z","size":317,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-02-12T23:47:03.652Z","etag":null,"topics":["definition","inject","insert-script","insert-statements","macros","npm","npm-module","npm-package","snippet-injector","snippet-manager","text-processing"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JuroOravec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-30T22:52:00.000Z","updated_at":"2018-11-03T09:46:44.000Z","dependencies_parsed_at":"2022-09-17T10:10:58.169Z","dependency_job_id":null,"html_url":"https://github.com/JuroOravec/inject-definition","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuroOravec%2Finject-definition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuroOravec%2Finject-definition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuroOravec%2Finject-definition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuroOravec%2Finject-definition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JuroOravec","download_url":"https://codeload.github.com/JuroOravec/inject-definition/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241475142,"owners_count":19968896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["definition","inject","insert-script","insert-statements","macros","npm","npm-module","npm-package","snippet-injector","snippet-manager","text-processing"],"created_at":"2024-11-13T10:59:59.917Z","updated_at":"2026-04-25T22:34:19.393Z","avatar_url":"https://github.com/JuroOravec.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# inject-definition\n\n[![Build Status](https://travis-ci.org/JuroOravec/inject-definition.svg?branch=master)](https://travis-ci.org/JuroOravec/inject-definition) [![Coverage Status](https://coveralls.io/repos/github/JuroOravec/inject-definition/badge.svg?branch=master)](https://coveralls.io/github/JuroOravec/inject-definition?branch=master)\n\nInjection of user-defined code, definitions, macros, constants or other snippets to a text simply by defining the snippets and including the definiton keyword in the text. Insertion formatting is customizable for compatibility with other programming languages.\n\n## Installing\n\nInstall via npm\n\n```\nnpm install inject-definition\n```\n\nInstall via yarn\n\n```\nyarn add inject-definition -S\n```\n\nImport and initialize with `.init()`\n\n```javascript\nconst injectDefinition = require(\"inject-definition\");\nconst mathDefinitions = injectDefinition.init();\n```\n\n### Initialisation options\n\n`init()` accepts an object of options with the following properties:\n\n```javascript\n{\n  definitions: object,\n  // To customize the formatting of inserted definitions, override these:\n  declarationFormatter: function,\n  minifier: function,\n  variableNameReplacer: function,\n  variableNameRetriever: function\n}\n```\n\nSee **API \u003e Properties** for the descriptions of individual properties.\n\n## Overview\n\nTo inject definitions into a text, you need to:\n\n1. Create (define) new definitions with `define()`.\n2. Activate or deactivate those definitions that should/should not be used with `activate()` and `deactivate()`. Deactivated definitions will be ignored when processing a text with definitions. (Note: new definitions are active by default)\n3. Inject the definitions into the text with `inject()`.\n\nTo get a list of names of definition found in text, use `scan()`.\n\nTo get a list of values of definitions found in text, use `generate()`.\n\n`inject-definition` can be also used for injecting snippets that are formatted for other languages than JS. Consider definiting your own `variableNameReplacer`, `variableNameRetriever`, `declarationFormatter` methods if this is the goal.\n\nAdditionally, `minifier` function can be provided, which allows to minify the injected definitions of `inject()` or the output of `generate()`.\n\n## Examples\n\n#### 1. Add new definitions\n\n```javascript\n// Define non-string types\nmathDefinitions.define(\"multiply.double\", function double(x) {\n  return 2 * x;\n});\nmathDefinitions.define(\n  \"multiply.triple\",\n  function triple(x) {\n    return 3 * x;\n  },\n  { activate: false }\n);\n\n// Define strings that can be later interpreted as a variable\nmathDefinitions.define(\"constants.number.e\", \"const e = 2.71828;\");\nmathDefinitions.define(\"constants.number.pi\", \"const pi = 3.1415;\");\n\n// Definitions can depend on each other. The dependency definitions will be\n// automatically added along with the injected definitions.\nmathDefinitions.define(\n  \"constants.number.twoPi\",\n  \"const twoPi = 2 * constants.number.pi;\"\n);\n\n// Specify if the definition should be inactive on defining.\nmathDefinitions.define(\n  \"constants.number.threePi\",\n  \"const threePi = 3 * constants.number.pi;\",\n  {\n    activate: false\n  }\n);\n```\n\n#### 2. Remove a single or a group of existing definitions\n\n```javascript\n// undefines `constants.number` and all its children definitions\nmathDefinitions.undefine(\"constants.number\");\n\nmathDefinitions.has(\"constants.number.pi\"); // false\nmathDefinitions.has(\"constants.number.e\"); // false\n\n// alternatively use undefineAll to undefine all, all active or all inactive definitions.\nmathDefinitions.undefineAll();\n```\n\n#### 3. Activate or deactivate a single definition or all definitions of certain activity type\n\n```javascript\nmathDefinitions.deactivate(\"constants.number\");\nmathDefinitions.activate(\"multiply.double\");\n\n// alternatively use activateAll or deactivateAll to (de)activate all, all active or all inactive definitions.\nmathDefinitions.activateAll();\nmathDefinitions.deactivateAll();\n```\n\n#### Inject definitions into a text that might include defined keywords.\n\n```javascript\nmathDefinitions.define(\"multiply.double\", function double(x) {\n  return 2 * x;\n});\nmathDefinitions.define(\"constants.number.pi\", \"const pi = 3.1415;\");\nmathDefinitions.has(\"constants.number.pi\"); // true\n\nconst snippet = \"const x = multiply.double(32 + constants.number.pi);\";\n\n// `inject` injects the definitions into a string\nmathDefinitions.inject(snippet, { reference: true });\n\n// function _double0(x) {    // injected function\n// return 2 * x;\n// }\n// const _pi0 = 3.1415;     // injected variable\n// var multiply = { double: _double0}    // injected definitions objects\n// var constants = { number: { pi: _pi0 }}\n// const x = multiply.double(32 + constants.number.pi);    // original snippet\n```\n\n#### Get names or values of the definitions found in the text\n\n```javascript\nconst snippet = \"const x = multiply.double(32 + constants.number.pi);\";\n\n// `scan` returns a list of names found definitions.\nmathDefinitions.scan(snippet); // ['multiply.double', 'constants.number.pi']\n\n// `generate` returns a list values of found definitions.\nmathDefinitions.generate(snippet); // [function double(x), \"const pi = 3.1415;\"]\n```\n\n#### Check for existence or get a definition's value\n\n```javascript\nmathDefinitions.define(\"constants.number.e\", \"const e = 2.71828;\");\nmathDefinitions.define(\"constants.number.pi\", \"const pi = 3.1415;\");\n\nmathDefinitions.get(\"constants.number.e\"); // 'const e = 2.71828;'\nmathDefinitions.has(\"constants.number.pi\"); // true\n```\n\n## API\n\n## **Properties**\n\n### definitions\n\nAn object of definitions stored as a tree of nested definition objects. Each definition object has following structure:\n\n```javascript\n{\n  keyword: string; // Keyword thar recognises the definition.\n  value: any; // Any value stored as the definition\n  children: {\n    foo: definitionObject;\n    ...\n  } // An object of children definition objects.\n  active: boolean // Boolean of whether the definition is active.\n}\n```\n\n---\n\n### declarationFormatter\n\nA function that defines how definitions objects should be formatted when `inject` has option `reference: true`.\n\nE.g. if given a definition object `'foo'`, which has structure `{'bar': 42}`, the `declarationFormatter` may format this as `var foo = {'bar': 42}` (Default).\n\n`declarationFormatter` accepts a function of type `(definitionsObjectName: string, definitionsObject: object) =\u003e string`\n\n---\n\n### minifier\n\nA function that minifies a string of stringified definitions values of definitions found through `generate()` or `inject()`. There is no default minification.\n\n`minifier` accepts a function of type `(stringifiedDefinitions: string) =\u003e string`\n\n---\n\n### variableNameRetriever\n\nA function that returns the name of a variable (if there is one) that is being declared in a definition. Necessary for customizing the formatting of declared values. Default function handles simple JS declarations with `const`, `let`, `var` and `function` keywords (no unpacking).\n\n`variableNameRetriever` accepts a function of type `(definition: string) =\u003e string`\n\n---\n\n### variableNameReplacer\n\nA function that replaces a variable name (same as the one found with `variableNameRetriever`) with a new name. Necessary for customizing the formatting of declared values. Default function handles simple JS declarations with `const`, `let`, `var` and `function` keywords (no unpacking).\n\n`variableNameReplacer` accepts a function of type `(definition: string, oldVariableName: string, newVariableName: string) =\u003e string`\n\n## **Methods**\n\n### define(_path, definition[, options]_)\n\nCreates a new definition.\n\n**`path:`**`string | string[]` - A string or array of strings specifying the path to a definition. If as string, path components are separated by dot `'.'` .\n**`definition:`**`any` - Value of the definition. This can be anything.\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`activate:`**`boolean` - Whether the definition should be automatically activated. Inactive definitions will be ignored when scanning / generating / injecting text. Default: `true`\n\n---\n\n### undefine(_path_)\n\nRemoves a definition.\n\n**`path:`**`string | string[]` - A string or array of strings specifying the path to a definition. If as string, path components are separated by dot `'.'` .\n\n---\n\n### undefineAll()\n\nRemoves all definitions of a certain type.\n\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`select:`**`'all'`|`'active'`|`'inactive'` - Type of definitions that should be removed. Either all definitions, only active definitions or only inactive definitions. Default: `'all'`\n\n---\n\n### activate(_path_)\n\nActivates a definition. Active definitions are included when scanning / generating / injecting text.\n\n**`path:`**`string | string[]` - A string or array of strings specifying the path to a definition. If as string, path components are separated by dot `'.'` .\n\n---\n\n### activateAll()\n\nActivates all definitions. Active definitions are included when scanning / generating / injecting text.\n\n---\n\n### deactivate(_path_)\n\nDeactivates a definition. Inactive definitions will be ignored when scanning / generating / injecting text.\n\n**`path:`**`string | string[]` - A string or array of strings specifying the path to a definition. If as string, path components are separated by dot `'.'` .\n\n---\n\n### deactivateAll()\n\nDeactivates all definitions. Inactive definitions will be ignored when scanning / generating / injecting text.\n\n---\n\n### get(_path[, options]_)\n\nRetrieves value of a definition specified by path. Returns undefined if no definition can be found.\n\n**`path:`**`string | string[]` - A string or array of strings specifying the path to a definition. If as string, path components are separated by dot `'.'` .\n\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`select:`**`'all'`|`'active'`|`'inactive'` - Type of definitions that will be searched through. Either all, all active or all inactive definitons. Default: `'all'`\n\n---\n\n### getAll()\n\nRetrieves the definitions tree.\n\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`select:`**`'all'`|`'active'`|`'inactive'` - Type of definitions that populate the tree. Either all, all active or all inactive definitons. Default: `'all'`\n\n- **`type:`**`'full`|`'partial'`|`'condensed'` - Type of structure of each node in the tree. Default: `'full'`\n  - With `'full'`, each node has all properties (`value`, `keyword` , `active`, `children`).\n  - With `'partial'`, each node has only `value` and `children` properties.\n  - With `'condensed'`, each node is either an object of children nodes, or a value. (Note: Definitions that are not on terminal nodes are omitted from the condensed structure).\n\n---\n\n### has(_path[, options]_)\n\nChecks if a definition specified by a path exists, and returns `true` if so. Returns `false` otherwise.\n\n**`path:`**`string | string[]` - A string or array of strings specifying the path to a definition. If as string, path components are separated by dot `'.'` .\n\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`select:`**`'all'`|`'active'`|`'inactive'` - Type of definitions that will be searched through. Either all, all active or all inactive definitons. Default: `'all'`\n\n---\n\n### scan(_targetText[, options]_)\n\nReturns the keywords (names) of definitions that were found in `targetText`. Only active definitions are included.\n\n**`targetText:`**`string` - A string to be scanned for definitions.\n\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`delimeter:`**`string | false` - A string that joins the found definition keywords into a string. If set to `false`, an array of definition keywords is returned instead. Default: `false`\n\n- **`overwrite:`**`boolean` - Whether only the definitions found in `targetText` should be set as active. Deactivates all other definitions.\n\n---\n\n### generate(_targetText[, options]_)\n\nReturns the values of definitions that were found in `targetText`. Only active definitions are included.\n\n**`targetText:`**`string` - A string to be scanned for definitions.\n\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`delimeter:`**`string | false` - A string that joins the found definition values into a string. If set to `false`, an array of definition values is returned instead. Default: `false`\n\n- **`minify:`**`boolean` - Whether the resulting string should be minified according to the `minifier` function. Has effect only when `delimeter` is a string. Default: `false`\n\n- **`overwrite:`**`boolean` - Whether only the definitions found in `targetText` should be set as active. Deactivates all other definitions.\n\n---\n\n### inject(_targetText[, options]_)\n\nReturns `targetText` with definitions injected. Only active definitions are included.\n\n**`targetText:`**`string` - A string to be scanned for definitions.\n\n**`options:`**`object` - An object of options that can modify the behaviour of the process. Options are:\n\n- **`delimeter:`**`string` - A string that joins the found definitions.\n  Default: `'\\n'`\n\n- **`insertLocation:`**`string` - A string specifying the location where the definitions should be inserted. Available values: `'start'`, `'end'`, `'replace'`. Default: `'start'`\n\n- **`minify:`**`boolean` - Whether the injected definitions should be minified according to the `minifier` function. Default: `false`\n\n- **`overwrite:`**`boolean` - Whether only the definitions found in `targetText` should be set as active. Deactivates all other definitions.\n\n- **`reference:`**`boolean` - Whether the definition keywords found in `targetText` can be used as references. E.g. if `targetText` contains definition `'foo.bar'`, which defines a function `bar`, then setting `reference` to `true` allows to use `foo.bar` in-text as a function, e.g. `foo.bar(x)` To enable this, a tree of definition objects for each of the top-level keywords is inserted after the definitions, e.g. `var foo = {bar: function(x){...}}`. Useful if the definitions are nested (E.g. `'a.b.c'`), and the definition values are programmatically referenced. (Note: Only terminal nodes can be referenced, e.g. `foo.bar`, but not `foo`). Default: `false`\n\n- **`separator:`**`string` - A string that joins definitions with the original text. Default: `'\\n'`\n\n## Running the tests\n\nRun tests with\n\n```\nnpm test\n```\n\nor\n\n```\nyarn test\n```\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](https://github.com/JuroOravec/inject-definition/blob/master/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n## Change-log\n\n- **2.0.0**\n  - Reworked definition tree structure and removed `activeDefinitions` object.\n  - Removed `activeDefinitions` option from `init()` options.\n  - Added `undefineAll()`\n  - Added `activateAll()`\n  - Added `deactivateAll()`\n  - Added `getAll()`\n  - Minifier affects only the string of joined definitions, not the original text\n  - Renamed options property `overwriteActiveDefinitions` to `overwrite`.\n  - Renamed options property `includeDefinitionsObjects` to `reference`.\n  - If definitions use other definitions these dependency definitions will be automatically included.\n\n* **1.0.0** - Initial release.\n\n## Authors\n\n- [**Juro Oravec**](https://github.com/https://github.com/JuroOravec)\n\nSee also the list of [contributors](https://github.com/JuroOravec/inject-definition/graphs/contributors) who participated in this project.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjurooravec%2Finject-definition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjurooravec%2Finject-definition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjurooravec%2Finject-definition/lists"}