You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This package offers several helper functions that delegate to the native Filesystem API — i.e. `node:fs` — when using the Node.js runtime. However, in any other environment — such as the browser — these functions will throw a `CODAMA_ERROR__NODE_FILESYSTEM_FUNCTION_UNAVAILABLE` error as a Filesystem API is not available. This enables us to write renderers regardless of the runtime environment.
23
+
This package offers several helper functions that delegate to the native Filesystem API — i.e. `node:fs` — when using the Node.js runtime. However, in any other environment — such as the browser — these functions will throw a `CODAMA_ERROR__NODE_FILESYSTEM_FUNCTION_UNAVAILABLE` error as a Filesystem API is not available. This enables us to import renderers regardless of the runtime environment.
24
24
25
-
```ts
26
-
// Reads the UTF-8 content of a file as a JSON object.
27
-
const json =readJson<MyJsonDefinition>(filePath);
25
+
### `createDirectory`
26
+
27
+
Creates a directory at the given path, recursively.
28
28
29
-
// Creates a directory at the given path, recursively.
29
+
```ts
30
30
createDirectory(newDirectoryPath);
31
+
```
32
+
33
+
### `deleteDirectory`
31
34
32
-
// Deletes a directory, recursively, if it exists.
35
+
Deletes a directory, recursively, if it exists.
36
+
37
+
```ts
33
38
deleteDirectory(directoryPath);
39
+
```
34
40
35
-
// Creates a new file at the given path with the given content.
36
-
// Creates its parent directory, recursively, if it does not exist.
41
+
### `writeFile`
42
+
43
+
Creates a new file at the given path with the given content. Creates its parent directory, recursively, if it does not exist.
44
+
45
+
```ts
37
46
writeFile(filePath, content);
38
47
```
39
48
49
+
### `readFile`
50
+
51
+
Reads the UTF-8 content of a file as a string.
52
+
53
+
```ts
54
+
const content =readFile(filePath);
55
+
```
56
+
57
+
### `readJson`
58
+
59
+
Reads the UTF-8 content of a file as a JSON object.
60
+
61
+
```ts
62
+
const json =readJson<MyJsonDefinition>(filePath);
63
+
```
64
+
65
+
## Path wrappers
66
+
67
+
This package also offers several `path` helpers that delegate to the native `node:path` module when using the Node.js runtime but provide a fallback implementation when using any other runtime.
The concept of fragments is commonly used in Codama renderers as a way to combine a piece of code with any context that is relevant to that piece of code. For instance, a fragment may include a dependency map that lists all the module imports required by that piece of code.
88
+
89
+
Since fragments vary from one renderer to another, this package cannot provide a one-size-fits-all `Fragment` type. Instead, it provides some base types and utility functions that can be used to build more specific fragment types.
90
+
91
+
### `BaseFragment`
92
+
93
+
The `BaseFragment` type is an object that includes a `content` string. Renderers may extend this type to include any additional context they need.
The `createFragmentTemplate` helper can be used to create [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) functions. For this, you need to provide a function that can merge multiple fragments together and a function that can identify fragments from other values.
118
+
119
+
```ts
120
+
function fragment(template:TemplateStringsArray, ...items:unknown[]):Fragment {
The `RenderMap` class is a utility class that helps manage a collection of files to be rendered. It acts as a middleman between the logic that generates the content and the logic that writes the content to the filesystem. As such, it provides a way to access the generated content outside an environment that supports the Filesystem API — such as the browser. It also helps us write tests about the generated code without having to write it to the filesystem.
130
+
This package also provides a `RenderMap` type and a handful of helpers to work with it.
43
131
44
-
### Adding content to a `RenderMap`
132
+
A `RenderMap` is a utility type that helps manage a collection of files to be rendered. It acts as a middleman between the logic that generates the content and the logic that writes the content to the filesystem. As such, it provides a way to access the generated content outside an environment that supports the Filesystem API — such as the browser. It also helps us write tests about the generated code without having to write it to the filesystem.
45
133
46
-
The add content to a `RenderMap`, you can use the `add` method by providing a path and the content to be written to that path.
134
+
### Creating new `RenderMaps`
47
135
48
-
Note that the path should be **relative to the base directory** that will be provided when writing the `RenderMap` to the filesystem.
136
+
You can use the `createRenderMap` function with no arguments to create a new empty `RenderMap`.
49
137
50
138
```ts
51
-
const renderMap =newRenderMap()
52
-
.add('programs/token.ts', 'export type TokenProgram = { /* ... */ }')
53
-
.add('accounts/mint.ts', 'export type MintAccount = { /* ... */ }')
54
-
.add('instructions/transfer.ts', 'export function getTransferInstruction = { /* ... */ }');
139
+
const renderMap =createRenderMap();
55
140
```
56
141
57
-
Additionally, you can use the `mergeWith` method to merge multiple`RenderMap`instances together.
142
+
You may provide the path and content of a file to create a`RenderMap`with a single file.
58
143
59
144
```ts
60
-
const renderMapA =newRenderMap().add('programs/programA.ts', 'export type ProgramA = { /* ... */ }');
Finally, note that any time a `string` is expected as the content of a file, you may also provide a `BaseFragment` instead. In that case, only the `content` field of the fragment will be used.
To remove files from a `RenderMap`, simply use the `remove` method by providing the relative path of the file to be removed.
172
+
Note that when setting paths inside a `RenderMap`, they should be relative to the base directory that will be provided when writing the `RenderMap` to the filesystem. For instance, if we decide to use `src/generated` as the base directory when writing the `RenderMap`, then using a path such as `accounts/mint.ts` will result in the file being written to `src/generated/accounts/mint.ts`.
173
+
174
+
### Adding content to a `RenderMap`
175
+
176
+
To add content to a `RenderMap`, you may use the `addToRenderMap` function by providing the path and the content of the file to be added. Note that, here as well, the path should be relative to the base directory that will be provided when writing the `RenderMap` to the filesystem.
Since `RenderMaps` are immutable, you may want to use the `pipe` function from `@codama/visitors-core` — also available in `codama` — to chain multiple updates together.
The `RenderMap` class provides several methods to access the content of the files it manages. The `get` method returns the content of a file from its relative path. If the file does not exist on the `RenderMap`, a `CODAMA_ERROR__VISITORS__RENDER_MAP_KEY_NOT_FOUND` error will be thrown.
195
+
You may use the `mergeRenderMaps` helper to combine multiple `RenderMap` instances into a single one. If two `RenderMap` instances contain the same file path, the content from the latter will overwrite the content from the former.
To safely access the content of a file without throwing an error, you can use the `safeGet` method. This method returns the content of a file from its relative path, or `undefined` if the file does not exist.
203
+
### Removing content from a `RenderMap`
204
+
205
+
To remove files from a `RenderMap`, simply use the `removeFromRenderMap` function by providing the relative path of the file to be removed.
The `has` and `isEmpty` methods can also be used to verify the existence of files in the `RenderMap`.
211
+
### Accessing content from a `RenderMap`
212
+
213
+
The `RenderMap` type is essentially a JavaScript `Map` so you can use all the methods available on the `Map` prototype. Therefore, you may use the `get` method to access the content of a file from its relative path.
Finally, the `contains` method can be used to check if a file contains a specific string or matches a regular expression.
219
+
However, this may return `undefined` if the file does not exist on the `RenderMap`. If you want to access the content of a file and throw an error if it does not exist, you can use the `getFromRenderMap` helper instead.
You may also use the `renderMapContains` helper to check if the provided file content exists in the `RenderMap` at the given path. The expected file content can be a string or a regular expression.
102
226
103
-
To map the content of files inside a `RenderMap`, you can use the `mapContent` method. This method accepts a function that takes the content of a file and returns a new content.
To map the content of all files inside a `RenderMap`, you can use the `mapRenderMapContent` function. This method accepts a function that takes the content of a file and returns a new content.
104
235
105
236
```ts
106
-
renderMap.mapContent(content=>`/** Prefix for all files */\n\n${content}`);
237
+
const updatedRenderMap =mapRenderMapContent(renderMap, c=>`/** Prefix for all files */\n\n${c}`);
107
238
```
108
239
109
-
An asynchronous version of this method called `mapContentAsync` is also available in case the transformation function needs to be asynchronous.
240
+
An asynchronous version of this function called `mapRenderMapContentAsync` is also available in case the transformation function needs to be asynchronous.
return`/** Prefix for all files */\n\n${transformedContent}`;
115
246
});
116
247
```
117
248
118
249
### Writing a `RenderMap` to the filesystem
119
250
120
-
When the `RenderMap` is ready to be written to the filesystem, you can use the `write` method by providing the base directory where all files should be written. Any relative path provided by the `add` method will be appended to this base directory.
251
+
When the `RenderMap` is ready to be written to the filesystem, you can use the `writeRenderMap` helper by providing the base directory where all files should be written. All paths inside the `RenderMap` will be appended to this base directory.
121
252
122
253
```ts
123
-
const renderMap =newRenderMap()
124
-
.add('programs/token.ts', 'export type TokenProgram = { /* ... */ }')
125
-
.add('accounts/mint.ts', 'export type MintAccount = { /* ... */ }');
254
+
const renderMap =createRenderMap({
255
+
'programs/token.ts': 'export type TokenProgram = { /* ... */ }',
256
+
'accounts/mint.ts': 'export type MintAccount = { /* ... */ }',
257
+
});
126
258
127
-
renderMap.write('src/generated');
259
+
writeRenderMap(renderMap, 'src/generated');
128
260
// In this example, files will be written to:
129
261
// - src/generated/programs/token.ts
130
262
// - src/generated/accounts/mint.ts.
131
263
```
132
264
133
265
### Using visitors
134
266
135
-
When building renderers, you will most likely create a visitor that traverses the Codama IDL and returns a `RenderMap`. That way, you can test the generated content without having to write it to the filesystem. For instance, the [`@codama/renderers-js`](../renderers-js) package exports a `getRenderMapVisitor` function that does just that.
267
+
When building renderers, you will most likely create a visitor that traverses the Codama IDL and returns a `RenderMap`. That way, you can test the generated content without having to write it to the filesystem. For instance, the [`@codama/renderers-js`](https://github.com/codama-idl/renderers-js) package exports a `getRenderMapVisitor` function that does just that.
Note however that, if you are writing your own renderer, you should probably offer a higher-level visitor that includes this logic and also does some additional work such as deleting the base directory before writing the new content if it already exists.
152
284
153
-
For instance, the recommended way of using the `@codama/renderers-js` package is to use the following `renderVisitor` function.
285
+
For instance, the recommended way of using the `@codama/renderers-js` package is to use its default exported visitor which does exactly that.
0 commit comments