refactor: extract fs and path helpers into runtime-utils

.changeset/spicy-rocks-lie.md

@@ -0,0 +1,5 @@
+---
+'@codama/runtime-utils': major
+---
+
+Add runtime-utils package providing filesystem and path helpers.

packages/renderers-core/README.md

@@ -18,70 +18,6 @@ pnpm install @codama/renderers-core
 > [!NOTE]
 > This package is **not** included in the main [`codama`](../library) package.
 
-## Filesystem wrappers
-
-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.
-
-### `createDirectory`
-
-Creates a directory at the given path, recursively.
-
-```ts
-createDirectory(newDirectoryPath);
-```
-
-### `deleteDirectory`
-
-Deletes a directory, recursively, if it exists.
-
-```ts
-deleteDirectory(directoryPath);
-```
-
-### `writeFile`
-
-Creates a new file at the given path with the given content. Creates its parent directory, recursively, if it does not exist.
-
-```ts
-writeFile(filePath, content);
-```
-
-### `readFile`
-
-Reads the UTF-8 content of a file as a string.
-
-```ts
-const content = readFile(filePath);
-```
-
-### `readJson`
-
-Reads the UTF-8 content of a file as a JSON object.
-
-```ts
-const json = readJson<MyJsonDefinition>(filePath);
-```
-
-## Path wrappers
-
-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.
-
-### `joinPath`
-
-Joins multiple path segments into a single path.
-
-```ts
-const path = joinPath('path', 'to', 'my', 'file.ts');
-```
-
-### `pathDirectory`
-
-Returns the parent directory of a given path.
-
-```ts
-const parentPath = pathDirectory(path);
-```
-
 ## Fragments
 
 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.

packages/renderers-core/package.json

@@ -47,7 +47,8 @@
     "dependencies": {
         "@codama/errors": "workspace:*",
         "@codama/nodes": "workspace:*",
-        "@codama/visitors-core": "workspace:*"
+        "@codama/visitors-core": "workspace:*",
+        "@codama/runtime-utils": "workspace:*"
     },
     "license": "MIT",
     "repository": {

packages/renderers-core/src/index.ts

@@ -1,4 +1,3 @@
 export * from './fragment';
-export * from './fs';
-export * from './path';
 export * from './renderMap';
+export * from '@codama/runtime-utils';

packages/renderers-core/src/renderMap.ts

@@ -1,10 +1,10 @@
 import { CODAMA_ERROR__VISITORS__RENDER_MAP_KEY_NOT_FOUND, CodamaError } from '@codama/errors';
 import { NodeKind } from '@codama/nodes';
+import { writeFile } from '@codama/runtime-utils';
+import { joinPath, Path } from '@codama/runtime-utils';
 import { mapVisitor, Visitor } from '@codama/visitors-core';
 
 import { BaseFragment, mapFragmentContent, mapFragmentContentAsync } from './fragment';
-import { writeFile } from './fs';
-import { joinPath, Path } from './path';
 
 export type RenderMap<TFragment extends BaseFragment> = ReadonlyMap<Path, TFragment>;
 

packages/runtime-utils/.gitignore

@@ -0,0 +1 @@
+/dist

packages/runtime-utils/.prettierignore

@@ -0,0 +1,5 @@
+dist/
+test/e2e/
+test-ledger/
+target/
+CHANGELOG.md

packages/runtime-utils/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Codama
+Copyright (c) 2024 Metaplex Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/runtime-utils/README.md

@@ -0,0 +1,80 @@
+# Codama ➤ Runtime Utilities
+
+This package provides runtime-safe filesystem and path utilities shared across Codama packages.
+Its primary goal is to centralize interactions with Node.js–specific APIs while allowing Codama
+packages (including renderers) to be imported in non-Node environments.
+
+These utilities are primarily consumed by renderer packages such as [`@codama/renderers-js`](https://github.com/codama-idl/renderers-js) and [`@codama/renderers-rust`](https://github.com/codama-idl/renderers-rust).
+
+## Installation
+
+```sh
+pnpm install @codama/runtime-utils
+```
+
+> [!NOTE]
+> This package is **not** included in the main [`codama`](../library) package.
+
+## Filesystem wrappers
+
+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 Codama packages (including renderers) to be imported regardless of the runtime environment.
+
+### `createDirectory`
+
+Creates a directory at the given path, recursively.
+
+```ts
+createDirectory(newDirectoryPath);
+```
+
+### `deleteDirectory`
+
+Deletes a directory, recursively, if it exists.
+
+```ts
+deleteDirectory(directoryPath);
+```
+
+### `writeFile`
+
+Creates a new file at the given path with the given content. Creates its parent directory, recursively, if it does not exist.
+
+```ts
+writeFile(filePath, content);
+```
+
+### `readFile`
+
+Reads the UTF-8 content of a file as a string.
+
+```ts
+const content = readFile(filePath);
+```
+
+### `readJson`
+
+Reads the UTF-8 content of a file as a JSON object.
+
+```ts
+const json = readJson<MyJsonDefinition>(filePath);
+```
+
+## Path wrappers
+
+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.
+
+### `joinPath`
+
+Joins multiple path segments into a single path.
+
+```ts
+const path = joinPath('path', 'to', 'my', 'file.ts');
+```
+
+### `pathDirectory`
+
+Returns the parent directory of a given path.
+
+```ts
+const parentPath = pathDirectory(path);
+```

packages/runtime-utils/package.json

@@ -0,0 +1,64 @@
+{
+    "name": "@codama/runtime-utils",
+    "version": "1.0.0",
+    "description": "Fs and Path helpers for Codama renderers to use",
+    "exports": {
+        "types": "./dist/types/index.d.ts",
+        "react-native": "./dist/index.react-native.mjs",
+        "browser": {
+            "import": "./dist/index.browser.mjs",
+            "require": "./dist/index.browser.cjs"
+        },
+        "node": {
+            "import": "./dist/index.node.mjs",
+            "require": "./dist/index.node.cjs"
+        }
+    },
+    "browser": {
+        "./dist/index.node.cjs": "./dist/index.browser.cjs",
+        "./dist/index.node.mjs": "./dist/index.browser.mjs"
+    },
+    "main": "./dist/index.node.cjs",
+    "module": "./dist/index.node.mjs",
+    "react-native": "./dist/index.react-native.mjs",
+    "types": "./dist/types/index.d.ts",
+    "type": "commonjs",
+    "files": [
+        "./dist/types",
+        "./dist/index.*"
+    ],
+    "sideEffects": false,
+    "keywords": [
+        "solana",
+        "framework",
+        "standard",
+        "visitors"
+    ],
+    "scripts": {
+        "build": "rimraf dist && tsup && tsc -p ./tsconfig.declarations.json",
+        "dev": "vitest --project node",
+        "lint": "eslint . && prettier --check .",
+        "lint:fix": "eslint --fix . && prettier --write .",
+        "test": "pnpm test:types && pnpm test:treeshakability && pnpm test:unit",
+        "test:treeshakability": "for file in dist/index.*.mjs; do agadoo $file; done",
+        "test:types": "tsc --noEmit",
+        "test:unit": "vitest run"
+    },
+    "dependencies": {
+        "@codama/errors": "workspace:*",
+        "@codama/nodes": "workspace:*",
+        "@codama/visitors-core": "workspace:*"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/codama-idl/codama"
+    },
+    "bugs": {
+        "url": "http://github.com/codama-idl/codama/issues"
+    },
+    "browserslist": [
+        "supports bigint and not dead",
+        "maintained node versions"
+    ]
+}

packages/runtime-utils/src/index.ts

@@ -0,0 +1,2 @@
+export * from './fs';
+export * from './path';

packages/runtime-utils/src/types/global.d.ts

@@ -0,0 +1,6 @@
+declare const __BROWSER__: boolean;
+declare const __ESM__: boolean;
+declare const __NODEJS__: boolean;
+declare const __REACTNATIVE__: boolean;
+declare const __TEST__: boolean;
+declare const __VERSION__: string;

packages/runtime-utils/test/types/global.d.ts

@@ -0,0 +1,6 @@
+declare const __BROWSER__: boolean;
+declare const __ESM__: boolean;
+declare const __NODEJS__: boolean;
+declare const __REACTNATIVE__: boolean;
+declare const __TEST__: boolean;
+declare const __VERSION__: string;

packages/runtime-utils/tsconfig.declarations.json

@@ -0,0 +1,10 @@
+{
+    "compilerOptions": {
+        "declaration": true,
+        "declarationMap": true,
+        "emitDeclarationOnly": true,
+        "outDir": "./dist/types"
+    },
+    "extends": "./tsconfig.json",
+    "include": ["src/index.ts", "src/types"]
+}

packages/runtime-utils/tsconfig.json

@@ -0,0 +1,7 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "compilerOptions": { "lib": [] },
+    "display": "@codama/runtime-utils",
+    "extends": "../../tsconfig.json",
+    "include": ["src", "test"]
+}

packages/runtime-utils/tsup.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'tsup';
+
+import { getPackageBuildConfigs } from '../../tsup.config.base';
+
+export default defineConfig(getPackageBuildConfigs());

packages/runtime-utils/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+import { getVitestConfig } from '../../vitest.config.base.mjs';
+
+export default defineConfig({
+    test: {
+        projects: [getVitestConfig('browser'), getVitestConfig('node'), getVitestConfig('react-native')],
+    },
+});