Skip to content

Commit 8dc5cad

Browse files
committed
docs(templatizer): fix incorrect README content
Replace incorrect ETag/S3 MD5 description (copied from etag-stream) with accurate documentation describing templatizer's actual functionality: - Template compilation and rendering system - Usage examples for local and GitHub template sources - API documentation for template functions - Template variable format documentation
1 parent 837e572 commit 8dc5cad

1 file changed

Lines changed: 101 additions & 4 deletions

File tree

packages/templatizer/README.md

Lines changed: 101 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,117 @@
99
<img height="20" src="https://github.com/launchql/launchql/actions/workflows/run-tests.yaml/badge.svg" />
1010
</a>
1111
<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>
1313
</p>
1414

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.
1616

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.
1818

1919
## Installation
2020

2121
```sh
2222
npm install @launchql/templatizer
2323
```
2424

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+
25123
## Related LaunchQL Tooling
26124

27125
### 🧪 Testing
@@ -66,4 +164,3 @@ npm install @launchql/templatizer
66164
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
67165

68166
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

Comments
 (0)