@jsxtools/rollup-plugin-utils

@jsxtools/rollup-plugin-utils

@jsxtools/rollup-plugin-utils is a collection of utilities for authoring Rollup plugins.

This package includes utilities for virtual asset management, file operations, path resolution, array/string manipulation, JSON handling, and option processing.

Installation

npm install @jsxtools/rollup-plugin-utils

Usage

This package provides several utility modules that can be imported individually:

import * as fs from "@jsxtools/rollup-plugin-utils/file";
import * as arr from "@jsxtools/rollup-plugin-utils/array";
import * as json from "@jsxtools/rollup-plugin-utils/json";
import * as str from "@jsxtools/rollup-plugin-utils/string";
import * as path from "@jsxtools/rollup-plugin-utils/path";

import { VirtualAsset } from "@jsxtools/rollup-plugin-utils/virtual-asset";
import { toArray, toMergedArray, assignInput } from "@jsxtools/rollup-plugin-utils/options";

Available Utilities

VirtualAsset

A utility class for managing virtual assets in Rollup builds. The constructor takes a required id string as the first parameter and automatically generates virtual module IDs using Rollup built-ins.

import { VirtualAsset } from "@jsxtools/rollup-plugin-utils/virtual-asset";

const virtualAsset = new VirtualAsset("my-virtual-asset", {
	load(context, id) {
		if (id === this.virtualId) {
			return { code: 'export const data = "virtual";' };
		}
	},
});

// Use in a plugin
export default {
	name: "my-plugin",
	buildStart(options) {
		virtualAsset.buildStart(this, options);
	},
	resolveId(id, importer, options) {
		return virtualAsset.resolveId(this, id, importer, options);
	},
	load(id) {
		return virtualAsset.load(this, id);
	},
	generateBundle(options, bundle) {
		virtualAsset.generateBundle(this, options, bundle);
	},
};

File Utilities

Utilities for file operations including hashing, copying, globbing, and reading.

import { hash, copyFile, glob, readJSON, ensureFileDir } from "@jsxtools/rollup-plugin-utils/file";

// Generate SHA-256 hash of a file
const fileHash = await hash("path/to/file.js");
console.log(fileHash); // "a1b2c3d4e5f6..."

// Copy file with CoW optimization when available
await copyFile("src/file.js", "dist/file.js");

// Glob for files
for await (const filePath of glob({
	include: "**/*.js",
	exclude: "**/*.test.js",
	cwd: new URL(".", import.meta.url),
})) {
	console.log(filePath);
}

// Read and parse JSON file
const config = await readJSON("config.json");

// Ensure directory exists for files
await ensureFileDir("dist/nested/file.js", "dist/other/file.js");

Array Utilities

Utilities for array manipulation and validation.

import { from, merge, every, isArray } from '@jsxtools/rollup-plugin-utils/array'

// Convert to array, filtering nulls
const files = from('file.js') // ['file.js']
const moreFiles = from(['a.js', 'b.js']) // ['a.js', 'b.js']
const noFiles = from(null) // []
const filtered = from([1, null, 2, undefined, 3]) // [1, 2, 3]

// Merge arrays safely
const merged = merge(['a.js'], ['b.js']) // ['a.js', 'b.js']
const withNulls = merge(null, ['b.js']) // ['b.js']

// Check if all items match predicate
const allStrings = every(['a', 'b'], (x): x is string => typeof x === 'string') // true

JSON Utilities

Utilities for JSON parsing and stringification with error handling.

import { from, to } from "@jsxtools/rollup-plugin-utils/json";

// Parse JSON safely (returns undefined on error)
const data = from('{"key": "value"}'); // { key: 'value' }
const invalid = from("invalid json"); // undefined

// Stringify JSON
const json = to({ key: "value" }); // '{"key":"value"}'
const pretty = to({ key: "value" }, null, 2); // formatted with 2 spaces

String Utilities

Utilities for string manipulation and validation.

import { from, trim, hasTrimmedValue } from "@jsxtools/rollup-plugin-utils/string";

// Convert to string (null/undefined becomes empty string)
const str = from("hello"); // 'hello'
const empty = from(null); // ''

// Trim string
const trimmed = trim("  hello  "); // 'hello'

// Check if string has non-empty trimmed value
if (hasTrimmedValue(input)) {
	// TypeScript knows input is a non-empty string
}

Options

Utilities for handling plugin options.

import { toArray, toMergedArray, assignInput } from "@jsxtools/rollup-plugin-utils/options";

// Convert single values or arrays to arrays
const files = toArray("file.js"); // ['file.js']
const moreFiles = toArray(["a.js", "b.js"]); // ['a.js', 'b.js']
const noFiles = toArray(null); // []

// Merge arrays safely
const merged = toMergedArray(["a.js"], ["b.js"]); // ['a.js', 'b.js']
const withNulls = toMergedArray(null, ["b.js"]); // ['b.js']

// Add input to Rollup options
const plugin = {
	name: "my-plugin",
	buildStart(options) {
		assignInput(options.input, "src/another-file.js");
	},
};

Path

Path resolution and manipulation utilities using URL objects.

import { toURL, toDirURL, toRelativePath, toParentURL } from "@jsxtools/rollup-plugin-utils/path";

// Convert to URL (absolute path)
const fileUrl = toURL("src", "index.js"); // URL { href: 'file:///absolute/path/to/src/index.js' }

// Convert to directory URL (with trailing slash)
const srcDir = toDirURL("src"); // URL { href: 'file:///absolute/path/to/src/' }
const distDir = toDirURL("dist", "assets"); // URL { href: 'file:///absolute/path/to/dist/assets/' }

// Get relative path between URLs
const rel = toRelativePath(new URL("file:///project/src/"), new URL("file:///project/dist/file.js")); // '../dist/file.js'

// Get parent directory URL
const parent = toParentURL(new URL("file:///project/src/file.js"));
// URL { href: 'file:///project/src/' }

API Reference

VirtualAsset

• constructor(id: string, hooks?: Partial<VirtualAsset.Hooks>) - Create a virtual asset with required ID and optional hooks
• id - Get/set the asset ID
• virtualId - Get the virtual module ID (prefixed with \0 and suffixed with /)
• buildStart(context, options) - Initialize the virtual asset during build start
• resolveId(context, id, importer, options) - Resolve virtual asset IDs
• load(context, id) - Load virtual asset content
• generateBundle(context, options, bundle) - Clean up virtual assets from bundle

File Utilities

• hash(file: PathLike): Promise<string> - Generate SHA-256 hash of file using streams
• copyFile(src: PathLike, dest: PathLike): Promise<void> - Copy file with CoW optimization
• glob(options?: GlobOptions): AsyncGenerator<string> - Async generator yielding file paths
• readJSON<T>(file: PathLike): Promise<T> - Read and parse JSON file
• ensureFileDir(...files: PathLike[]): Promise<void> - Ensure directories exist for files
• mkdir(path: PathLike): Promise<string | undefined> - Create directory recursively
• readFile, writeFile, deleteFile, getFileStats - Re-exports from node:fs/promises

Array Utilities

• from<T>(items: T | T[] | null | undefined, predicate?): T[] - Convert to array, filtering by predicate
• merge<T>(a?: T[], b?: T[]): T[] - Merge two arrays safely
• every<T>(value: unknown, predicate): value is T[] - Check if value is array and all items match predicate
• isArray(value: unknown): value is Array - Check if value is an array

JSON Utilities

• from<T>(json: string, reviver?): T | undefined - Parse JSON safely (returns undefined on error)
• to(value: unknown, replacer?, space?): string - Stringify JSON

String Utilities

• from(value: unknown): string - Convert to string (null/undefined becomes empty string)
• trim(value: unknown): string - Convert to trimmed string
• hasTrimmedValue<T>(value: T): value is HasValue<T> - Check if string has non-empty trimmed value

Options

• toArray<T>(items: T | T[] | null | undefined): T[] - Convert to array, filtering nulls
• toMergedArray<T>(a?: T[], b?: T[]): T[] - Merge two arrays safely
• assignInput<T>(input: T, id: string): T - Add an ID to Rollup input option

Path

• toURL(...paths: string[]): URL - Resolve paths to file URL
• toDirURL(...paths: string[]): URL - Resolve paths to directory URL (with trailing slash)
• toRelativePath(from: URL, to: URL): string - Get relative POSIX path between URLs
• toParentURL(url: URL): URL - Get parent directory URL
• PathLike - Type alias for string | URL

Exports

• @jsxtools/rollup-plugin-utils/array - Array manipulation utilities
• @jsxtools/rollup-plugin-utils/file - File operation utilities
• @jsxtools/rollup-plugin-utils/json - JSON parsing/stringification utilities
• @jsxtools/rollup-plugin-utils/string - String manipulation utilities
• @jsxtools/rollup-plugin-utils/options - Options handling utilities
• @jsxtools/rollup-plugin-utils/path - Path utilities
• @jsxtools/rollup-plugin-utils/virtual-asset - Virtual asset management

Peer Dependencies

• rollup ^4.6.0

License

MIT-0