|
9 | 9 | <img height="20" src="https://github.com/launchql/launchql/actions/workflows/run-tests.yaml/badge.svg" /> |
10 | 10 | </a> |
11 | 11 | <a href="https://github.com/launchql/launchql/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a> |
12 | | - <a href="https://www.npmjs.com/package/templatizer"><img height="20" src="https://img.shields.io/github/package-json/v/launchql/launchql?filename=packages%2Ftemplatizer%2Fpackage.json"/></a> |
| 12 | + <a href="https://www.npmjs.com/package/@launchql/templatizer"><img height="20" src="https://img.shields.io/github/package-json/v/launchql/launchql?filename=packages%2Ftemplatizer%2Fpackage.json"/></a> |
13 | 13 | </p> |
14 | 14 |
|
15 | | -Calculates Etag/S3 MD5 sum given a readable stream. Uses the same algorithm that S3 uses to calculate the `ETag`. |
| 15 | +Template compilation and rendering system for LaunchQL boilerplates. Compiles template directories into executable function arrays with variable substitution support. |
16 | 16 |
|
17 | | -This is especially useful for verifying large files uploaded using multipart S3 API, enabling use of `createReadStream` to keep memory usage low. |
| 17 | +This package is used by the `lql init` command to generate new workspace and module projects from boilerplate templates. It supports loading templates from local paths or GitHub repositories. |
18 | 18 |
|
19 | 19 | ## Installation |
20 | 20 |
|
21 | 21 | ```sh |
22 | 22 | npm install @launchql/templatizer |
23 | 23 | ``` |
24 | 24 |
|
| 25 | +## Features |
| 26 | + |
| 27 | +- **Template Compilation**: Convert boilerplate directories into compiled template functions |
| 28 | +- **Variable Substitution**: Support for `__VARIABLE__` style placeholders in file paths and content |
| 29 | +- **Custom Template Sources**: Load templates from local paths or GitHub repositories |
| 30 | +- **Type Safety**: Full TypeScript support with type definitions |
| 31 | + |
| 32 | +## Usage |
| 33 | + |
| 34 | +### Using Pre-compiled Templates |
| 35 | + |
| 36 | +```typescript |
| 37 | +import { workspaceTemplate, writeRenderedTemplates } from '@launchql/templatizer'; |
| 38 | + |
| 39 | +const vars = { |
| 40 | + MODULENAME: 'my-workspace', |
| 41 | + USERNAME: 'myuser', |
| 42 | + USERFULLNAME: 'My Name', |
| 43 | + USEREMAIL: 'my@email.com' |
| 44 | +}; |
| 45 | + |
| 46 | +writeRenderedTemplates(workspaceTemplate, './output-dir', vars); |
| 47 | +``` |
| 48 | + |
| 49 | +### Loading Templates from Custom Sources |
| 50 | + |
| 51 | +```typescript |
| 52 | +import { loadTemplates, writeRenderedTemplates, TemplateSource } from '@launchql/templatizer'; |
| 53 | + |
| 54 | +// Load from local path |
| 55 | +const localSource: TemplateSource = { |
| 56 | + type: 'local', |
| 57 | + path: './custom-templates/workspace' |
| 58 | +}; |
| 59 | + |
| 60 | +const templates = loadTemplates(localSource, 'workspace'); |
| 61 | +const rendered = templates.map(t => t.render); |
| 62 | +writeRenderedTemplates(rendered, './output-dir', vars); |
| 63 | + |
| 64 | +// Load from GitHub repository |
| 65 | +const githubSource: TemplateSource = { |
| 66 | + type: 'github', |
| 67 | + path: 'owner/repo', |
| 68 | + branch: 'main' // optional, defaults to 'main' |
| 69 | +}; |
| 70 | + |
| 71 | +const githubTemplates = loadTemplates(githubSource, 'workspace'); |
| 72 | +const githubRendered = githubTemplates.map(t => t.render); |
| 73 | +writeRenderedTemplates(githubRendered, './output-dir', vars); |
| 74 | +``` |
| 75 | + |
| 76 | +### Compiling Templates |
| 77 | + |
| 78 | +```typescript |
| 79 | +import { compileTemplatesToFunctions } from '@launchql/templatizer'; |
| 80 | + |
| 81 | +const templates = compileTemplatesToFunctions('./boilerplates/module'); |
| 82 | +// Returns CompiledTemplate[] with render functions |
| 83 | +``` |
| 84 | + |
| 85 | +## Template Variable Format |
| 86 | + |
| 87 | +Templates use the `__VARIABLE__` format for variable substitution in both file paths and content: |
| 88 | + |
| 89 | +- **File paths**: `__MODULENAME__/package.json` → `my-module/package.json` |
| 90 | +- **File content**: `"name": "__MODULENAME__"` → `"name": "my-module"` |
| 91 | + |
| 92 | +Variables are replaced at render time with values from the `vars` object passed to `writeRenderedTemplates()`. |
| 93 | + |
| 94 | +## API |
| 95 | + |
| 96 | +### `compileTemplatesToFunctions(srcDir: string): CompiledTemplate[]` |
| 97 | + |
| 98 | +Compiles all files in a directory into template functions. |
| 99 | + |
| 100 | +### `writeRenderedTemplates(templates: Func[], outDir: string, vars: Record<string, any>): void` |
| 101 | + |
| 102 | +Renders compiled templates and writes them to the output directory. |
| 103 | + |
| 104 | +### `loadTemplates(source: TemplateSource, templateType: 'workspace' | 'module'): CompiledTemplate[]` |
| 105 | + |
| 106 | +Loads templates from a local path or GitHub repository. |
| 107 | + |
| 108 | +### `TemplateSource` |
| 109 | + |
| 110 | +```typescript |
| 111 | +interface TemplateSource { |
| 112 | + type: 'local' | 'github'; |
| 113 | + path: string; |
| 114 | + branch?: string; // Optional, for GitHub sources |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +## Scripts |
| 119 | + |
| 120 | +- `makeTemplates`: Compiles boilerplates from `boilerplates/` directory into `src/generated/` TypeScript files |
| 121 | +- `generate`: Test script to render templates with sample variables |
| 122 | + |
25 | 123 | ## Related LaunchQL Tooling |
26 | 124 |
|
27 | 125 | ### 🧪 Testing |
@@ -66,4 +164,3 @@ npm install @launchql/templatizer |
66 | 164 | AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND. |
67 | 165 |
|
68 | 166 | No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value. |
69 | | - |
|
0 commit comments