Add filepath as second argument of RenderMap transform helpers (#948)

Author: lorisleiva

.changeset/solid-tables-decide.md

@@ -0,0 +1,5 @@
+---
+'@codama/renderers-core': patch
+---
+
+Add filepath as second argument of RenderMap transform helpers

packages/renderers-core/README.md

@@ -246,6 +246,12 @@ const updatedRenderMap = await mapRenderMapContentAsync(renderMap, async content
 });
 ```
 
+Note that in both cases, a second argument is available in the mapping function that provides the relative path of the file being transformed.
+
+```ts
+const updatedRenderMap = mapRenderMapContent(renderMap, (content, path) => `/** File: ${path} */\n\n${content}`);
+```
+
 ### Writing a `RenderMap` to the filesystem
 
 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.

packages/renderers-core/src/renderMap.ts

@@ -61,36 +61,40 @@ export function mergeRenderMaps<TFragment extends BaseFragment>(
 
 export function mapRenderMapFragment<TFragment extends BaseFragment>(
     renderMap: RenderMap<TFragment>,
-    fn: (fragment: TFragment) => TFragment,
+    fn: (fragment: TFragment, path: Path) => TFragment,
 ): RenderMap<TFragment> {
-    return Object.freeze(new Map([...[...renderMap.entries()].map(([key, value]) => [key, fn(value)] as const)]));
+    return Object.freeze(new Map([...[...renderMap.entries()].map(([key, value]) => [key, fn(value, key)] as const)]));
 }
 
 export async function mapRenderMapFragmentAsync<TFragment extends BaseFragment>(
     renderMap: RenderMap<TFragment>,
-    fn: (fragment: TFragment) => Promise<TFragment>,
+    fn: (fragment: TFragment, path: Path) => Promise<TFragment>,
 ): Promise<RenderMap<TFragment>> {
     return Object.freeze(
         new Map(
             await Promise.all([
-                ...[...renderMap.entries()].map(async ([key, value]) => [key, await fn(value)] as const),
+                ...[...renderMap.entries()].map(async ([key, value]) => [key, await fn(value, key)] as const),
             ]),
         ),
     );
 }
 
 export function mapRenderMapContent<TFragment extends BaseFragment>(
     renderMap: RenderMap<TFragment>,
-    fn: (content: string) => string,
+    fn: (content: string, path: Path) => string,
 ): RenderMap<TFragment> {
-    return mapRenderMapFragment(renderMap, fragment => mapFragmentContent(fragment, fn));
+    return mapRenderMapFragment(renderMap, (fragment, path) =>
+        mapFragmentContent(fragment, content => fn(content, path)),
+    );
 }
 
 export async function mapRenderMapContentAsync<TFragment extends BaseFragment>(
     renderMap: RenderMap<TFragment>,
-    fn: (content: string) => Promise<string>,
+    fn: (content: string, path: Path) => Promise<string>,
 ): Promise<RenderMap<TFragment>> {
-    return await mapRenderMapFragmentAsync(renderMap, fragment => mapFragmentContentAsync(fragment, fn));
+    return await mapRenderMapFragmentAsync(renderMap, (fragment, path) =>
+        mapFragmentContentAsync(fragment, content => fn(content, path)),
+    );
 }
 
 export function getFromRenderMap<TFragment extends BaseFragment>(

packages/renderers-core/test/renderMap.test.ts

@@ -152,7 +152,10 @@ describe('mapRenderMapContent', () => {
     test('it maps the content of all entries inside a render map', () => {
         expect(
             mapRenderMapContent(
-                createRenderMap({ pathA: { content: 'ContentA' }, pathB: { content: 'ContentB' } }),
+                createRenderMap({
+                    pathA: { content: 'ContentA' },
+                    pathB: { content: 'ContentB' },
+                }),
                 content => `Mapped: ${content}`,
             ),
         ).toStrictEqual(
@@ -163,6 +166,23 @@ describe('mapRenderMapContent', () => {
         );
     });
 
+    test('it provides the path of the content being mapped', () => {
+        expect(
+            mapRenderMapContent(
+                createRenderMap({
+                    pathA: { content: 'Content' },
+                    pathB: { content: 'Content' },
+                }),
+                (content, path) => `${content} from ${path}`,
+            ),
+        ).toStrictEqual(
+            new Map([
+                ['pathA', { content: 'Content from pathA' }],
+                ['pathB', { content: 'Content from pathB' }],
+            ]),
+        );
+    });
+
     test('it freezes the returned render map', () => {
         assert.isFrozen(mapRenderMapContent(createRenderMap(), c => c));
     });
@@ -186,6 +206,23 @@ describe('mapRenderMapContentAsync', () => {
         );
     });
 
+    test('it provides the path of the content being mapped', async () => {
+        expect(
+            await mapRenderMapContentAsync(
+                createRenderMap({
+                    pathA: { content: 'Content' },
+                    pathB: { content: 'Content' },
+                }),
+                (content, path) => Promise.resolve(`${content} from ${path}`),
+            ),
+        ).toStrictEqual(
+            new Map([
+                ['pathA', { content: 'Content from pathA' }],
+                ['pathB', { content: 'Content from pathB' }],
+            ]),
+        );
+    });
+
     test('it freezes the returned render map', async () => {
         assert.isFrozen(await mapRenderMapContentAsync(createRenderMap(), c => Promise.resolve(c)));
     });