From a113ba0e22c44606a5e6e8200881271c3eb377f5 Mon Sep 17 00:00:00 2001 From: JKrishnaD Date: Wed, 31 Dec 2025 14:51:27 +0530 Subject: [PATCH 1/3] refactor: extract fs and path helpers into runtime-utils --- packages/renderers-core/README.md | 64 --------------- packages/renderers-core/package.json | 3 +- packages/renderers-core/src/index.ts | 2 - packages/renderers-core/src/renderMap.ts | 4 +- packages/runtime-utils/.gitignore | 1 + packages/runtime-utils/.prettierignore | 5 ++ packages/runtime-utils/LICENSE | 23 ++++++ packages/runtime-utils/README.md | 80 +++++++++++++++++++ packages/runtime-utils/package.json | 64 +++++++++++++++ .../src/fs.ts | 0 packages/runtime-utils/src/index.ts | 2 + .../src/path.ts | 0 .../test/fs.test.json | 0 .../test/fs.test.ts | 0 .../test/path.test.ts | 0 packages/runtime-utils/test/types/global.d.ts | 6 ++ .../runtime-utils/tsconfig.declaration.json | 10 +++ packages/runtime-utils/tsconfig.json | 7 ++ packages/runtime-utils/tsup.config.ts | 5 ++ packages/runtime-utils/vitest.config.mts | 8 ++ 20 files changed, 215 insertions(+), 69 deletions(-) create mode 100644 packages/runtime-utils/.gitignore create mode 100644 packages/runtime-utils/.prettierignore create mode 100644 packages/runtime-utils/LICENSE create mode 100644 packages/runtime-utils/README.md create mode 100644 packages/runtime-utils/package.json rename packages/{renderers-core => runtime-utils}/src/fs.ts (100%) create mode 100644 packages/runtime-utils/src/index.ts rename packages/{renderers-core => runtime-utils}/src/path.ts (100%) rename packages/{renderers-core => runtime-utils}/test/fs.test.json (100%) rename packages/{renderers-core => runtime-utils}/test/fs.test.ts (100%) rename packages/{renderers-core => runtime-utils}/test/path.test.ts (100%) create mode 100644 packages/runtime-utils/test/types/global.d.ts create mode 100644 packages/runtime-utils/tsconfig.declaration.json create mode 100644 packages/runtime-utils/tsconfig.json create mode 100644 packages/runtime-utils/tsup.config.ts create mode 100644 packages/runtime-utils/vitest.config.mts diff --git a/packages/renderers-core/README.md b/packages/renderers-core/README.md index 4a81ee1d2..51fc9a5e3 100644 --- a/packages/renderers-core/README.md +++ b/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(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. diff --git a/packages/renderers-core/package.json b/packages/renderers-core/package.json index 58c69bfc9..7888f87d2 100644 --- a/packages/renderers-core/package.json +++ b/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/fs-path": "workspace:*" }, "license": "MIT", "repository": { diff --git a/packages/renderers-core/src/index.ts b/packages/renderers-core/src/index.ts index 8b9e82015..7b24231aa 100644 --- a/packages/renderers-core/src/index.ts +++ b/packages/renderers-core/src/index.ts @@ -1,4 +1,2 @@ export * from './fragment'; -export * from './fs'; -export * from './path'; export * from './renderMap'; diff --git a/packages/renderers-core/src/renderMap.ts b/packages/renderers-core/src/renderMap.ts index 8ea6720e4..ae06b1a57 100644 --- a/packages/renderers-core/src/renderMap.ts +++ b/packages/renderers-core/src/renderMap.ts @@ -3,8 +3,8 @@ import { NodeKind } from '@codama/nodes'; import { mapVisitor, Visitor } from '@codama/visitors-core'; import { BaseFragment, mapFragmentContent, mapFragmentContentAsync } from './fragment'; -import { writeFile } from './fs'; -import { joinPath, Path } from './path'; +import { writeFile } from '@codama/runtime-utils'; +import { joinPath, Path } from '@codama/runtime-utils'; export type RenderMap = ReadonlyMap; diff --git a/packages/runtime-utils/.gitignore b/packages/runtime-utils/.gitignore new file mode 100644 index 000000000..9b1c8b133 --- /dev/null +++ b/packages/runtime-utils/.gitignore @@ -0,0 +1 @@ +/dist diff --git a/packages/runtime-utils/.prettierignore b/packages/runtime-utils/.prettierignore new file mode 100644 index 000000000..ebf37de71 --- /dev/null +++ b/packages/runtime-utils/.prettierignore @@ -0,0 +1,5 @@ +dist/ +test/e2e/ +test-ledger/ +target/ +CHANGELOG.md diff --git a/packages/runtime-utils/LICENSE b/packages/runtime-utils/LICENSE new file mode 100644 index 000000000..9c41ed7e1 --- /dev/null +++ b/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. diff --git a/packages/runtime-utils/README.md b/packages/runtime-utils/README.md new file mode 100644 index 000000000..484c2aeda --- /dev/null +++ b/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(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); +``` diff --git a/packages/runtime-utils/package.json b/packages/runtime-utils/package.json new file mode 100644 index 000000000..a71ffd3eb --- /dev/null +++ b/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" + ] +} diff --git a/packages/renderers-core/src/fs.ts b/packages/runtime-utils/src/fs.ts similarity index 100% rename from packages/renderers-core/src/fs.ts rename to packages/runtime-utils/src/fs.ts diff --git a/packages/runtime-utils/src/index.ts b/packages/runtime-utils/src/index.ts new file mode 100644 index 000000000..17bc9aa8f --- /dev/null +++ b/packages/runtime-utils/src/index.ts @@ -0,0 +1,2 @@ +export * from './fs'; +export * from './path'; diff --git a/packages/renderers-core/src/path.ts b/packages/runtime-utils/src/path.ts similarity index 100% rename from packages/renderers-core/src/path.ts rename to packages/runtime-utils/src/path.ts diff --git a/packages/renderers-core/test/fs.test.json b/packages/runtime-utils/test/fs.test.json similarity index 100% rename from packages/renderers-core/test/fs.test.json rename to packages/runtime-utils/test/fs.test.json diff --git a/packages/renderers-core/test/fs.test.ts b/packages/runtime-utils/test/fs.test.ts similarity index 100% rename from packages/renderers-core/test/fs.test.ts rename to packages/runtime-utils/test/fs.test.ts diff --git a/packages/renderers-core/test/path.test.ts b/packages/runtime-utils/test/path.test.ts similarity index 100% rename from packages/renderers-core/test/path.test.ts rename to packages/runtime-utils/test/path.test.ts diff --git a/packages/runtime-utils/test/types/global.d.ts b/packages/runtime-utils/test/types/global.d.ts new file mode 100644 index 000000000..13de8a7ce --- /dev/null +++ b/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; diff --git a/packages/runtime-utils/tsconfig.declaration.json b/packages/runtime-utils/tsconfig.declaration.json new file mode 100644 index 000000000..f6fff01f0 --- /dev/null +++ b/packages/runtime-utils/tsconfig.declaration.json @@ -0,0 +1,10 @@ +{ + "compilerOptions": { + "declaration": true, + "declarationMap": true, + "emitDeclarationOnly": true, + "outDir": "./dist/types", + }, + "extends": "./tsconfig.json", + "include": ["src/index.ts", "src/types"], +} diff --git a/packages/runtime-utils/tsconfig.json b/packages/runtime-utils/tsconfig.json new file mode 100644 index 000000000..fd1f9cde1 --- /dev/null +++ b/packages/runtime-utils/tsconfig.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json.schemastore.org/tsconfig", + "compilerOptions": { "lib": [] }, + "display": "@codama/fs-path", + "extends": "../../tsconfig.json", + "include": ["src", "test"], +} diff --git a/packages/runtime-utils/tsup.config.ts b/packages/runtime-utils/tsup.config.ts new file mode 100644 index 000000000..55e99457f --- /dev/null +++ b/packages/runtime-utils/tsup.config.ts @@ -0,0 +1,5 @@ +import { defineConfig } from 'tsup'; + +import { getPackageBuildConfigs } from '../../tsup.config.base'; + +export default defineConfig(getPackageBuildConfigs()); diff --git a/packages/runtime-utils/vitest.config.mts b/packages/runtime-utils/vitest.config.mts new file mode 100644 index 000000000..8fd0137cc --- /dev/null +++ b/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')], + }, +}); From a714f577c3920b90b495ac29fbbe2d6b7b7ede52 Mon Sep 17 00:00:00 2001 From: JKrishnaD Date: Tue, 6 Jan 2026 23:49:08 +0530 Subject: [PATCH 2/3] fix: integrate runtime-utils with proper types declarations --- packages/renderers-core/package.json | 2 +- packages/renderers-core/src/index.ts | 1 + packages/renderers-core/src/renderMap.ts | 4 ++-- packages/runtime-utils/src/types/global.d.ts | 6 ++++++ ...eclaration.json => tsconfig.declarations.json} | 4 ++-- packages/runtime-utils/tsconfig.json | 4 ++-- pnpm-lock.yaml | 15 +++++++++++++++ 7 files changed, 29 insertions(+), 7 deletions(-) create mode 100644 packages/runtime-utils/src/types/global.d.ts rename packages/runtime-utils/{tsconfig.declaration.json => tsconfig.declarations.json} (67%) diff --git a/packages/renderers-core/package.json b/packages/renderers-core/package.json index 7888f87d2..e2bea586c 100644 --- a/packages/renderers-core/package.json +++ b/packages/renderers-core/package.json @@ -48,7 +48,7 @@ "@codama/errors": "workspace:*", "@codama/nodes": "workspace:*", "@codama/visitors-core": "workspace:*", - "@codama/fs-path": "workspace:*" + "@codama/runtime-utils": "workspace:*" }, "license": "MIT", "repository": { diff --git a/packages/renderers-core/src/index.ts b/packages/renderers-core/src/index.ts index 7b24231aa..500a540fa 100644 --- a/packages/renderers-core/src/index.ts +++ b/packages/renderers-core/src/index.ts @@ -1,2 +1,3 @@ export * from './fragment'; export * from './renderMap'; +export * from '@codama/runtime-utils'; diff --git a/packages/renderers-core/src/renderMap.ts b/packages/renderers-core/src/renderMap.ts index ae06b1a57..45c1feafb 100644 --- a/packages/renderers-core/src/renderMap.ts +++ b/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 '@codama/runtime-utils'; -import { joinPath, Path } from '@codama/runtime-utils'; export type RenderMap = ReadonlyMap; diff --git a/packages/runtime-utils/src/types/global.d.ts b/packages/runtime-utils/src/types/global.d.ts new file mode 100644 index 000000000..13de8a7ce --- /dev/null +++ b/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; diff --git a/packages/runtime-utils/tsconfig.declaration.json b/packages/runtime-utils/tsconfig.declarations.json similarity index 67% rename from packages/runtime-utils/tsconfig.declaration.json rename to packages/runtime-utils/tsconfig.declarations.json index f6fff01f0..dc2d27bb0 100644 --- a/packages/runtime-utils/tsconfig.declaration.json +++ b/packages/runtime-utils/tsconfig.declarations.json @@ -3,8 +3,8 @@ "declaration": true, "declarationMap": true, "emitDeclarationOnly": true, - "outDir": "./dist/types", + "outDir": "./dist/types" }, "extends": "./tsconfig.json", - "include": ["src/index.ts", "src/types"], + "include": ["src/index.ts", "src/types"] } diff --git a/packages/runtime-utils/tsconfig.json b/packages/runtime-utils/tsconfig.json index fd1f9cde1..5aae8dfd8 100644 --- a/packages/runtime-utils/tsconfig.json +++ b/packages/runtime-utils/tsconfig.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/tsconfig", "compilerOptions": { "lib": [] }, - "display": "@codama/fs-path", + "display": "@codama/runtime-utils", "extends": "../../tsconfig.json", - "include": ["src", "test"], + "include": ["src", "test"] } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d3d7d9b88..477960d6c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -176,6 +176,21 @@ importers: version: 5.1.0(fastestsmallesttextencoderdecoder@1.0.22)(typescript@5.9.3) packages/renderers-core: + dependencies: + '@codama/errors': + specifier: workspace:* + version: link:../errors + '@codama/nodes': + specifier: workspace:* + version: link:../nodes + '@codama/runtime-utils': + specifier: workspace:* + version: link:../runtime-utils + '@codama/visitors-core': + specifier: workspace:* + version: link:../visitors-core + + packages/runtime-utils: dependencies: '@codama/errors': specifier: workspace:* From 05b268421606577eb190fc6d9e9bccacddb67928 Mon Sep 17 00:00:00 2001 From: JKrishnaD Date: Tue, 6 Jan 2026 23:50:16 +0530 Subject: [PATCH 3/3] chore: add changeset for runtime-utils --- .changeset/spicy-rocks-lie.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/spicy-rocks-lie.md diff --git a/.changeset/spicy-rocks-lie.md b/.changeset/spicy-rocks-lie.md new file mode 100644 index 000000000..5f57f8c09 --- /dev/null +++ b/.changeset/spicy-rocks-lie.md @@ -0,0 +1,5 @@ +--- +'@codama/runtime-utils': major +--- + +Add runtime-utils package providing filesystem and path helpers.