{"id":17593,"library":"eslint-barrel-file-utils","title":"Napi-rs Template Project (eslint-barrel-file-utils)","description":"The `eslint-barrel-file-utils` package serves as an example project built with `napi-rs`, a framework for constructing high-performance Node.js native addons using Rust. Currently at version 0.0.15, this package demonstrates the setup, build, testing, and release workflow for `napi-rs` projects rather than providing standalone ESLint utilities. Its release cadence is infrequent, aligning with updates to the underlying `napi-rs` template. A primary differentiator of `napi-rs` (and thus this template) is its robust, ABI-compatible native module generation across various operating systems (Windows, macOS, Linux, Android, FreeBSD) and Node.js versions (10, 14, 16, 18). It employs a unique distribution strategy where platform-specific binaries are published as separate `npm` packages and loaded via `optionalDependencies`, eliminating the need for users to install complex build toolchains like `node-gyp` for most use cases.","status":"maintenance","version":"0.0.15","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/thepassle/eslint-barrel-file-utils","tags":["javascript","napi-rs","NAPI","N-API","Rust","node-addon","node-addon-api","typescript"],"install":[{"cmd":"npm install eslint-barrel-file-utils","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-barrel-file-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-barrel-file-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ES Modules syntax is preferred; CommonJS `require` can be problematic with native addons and TypeScript types.","wrong":"const { syncFunction } = require('eslint-barrel-file-utils');","symbol":"syncFunction","correct":"import { syncFunction } from 'eslint-barrel-file-utils';"},{"note":"Named exports are used for functions exposed from the native addon.","wrong":"const sleepFunction = require('eslint-barrel-file-utils').sleepFunction;","symbol":"sleepFunction","correct":"import { sleepFunction } from 'eslint-barrel-file-utils';"},{"note":"There is no default export; the native module exports multiple named functions. Use `* as` for grouping.","wrong":"import NativeAddonModule from 'eslint-barrel-file-utils';","symbol":"NativeAddonModule","correct":"import * as NativeAddonModule from 'eslint-barrel-file-utils';"}],"quickstart":{"code":"import { syncFunction, sleepFunction } from 'eslint-barrel-file-utils';\n\nconsole.log('Calling synchronous native function...');\nconst result = syncFunction();\nconsole.log(`Sync function returned: ${result}`);\n\nconsole.log('Calling asynchronous native function (sleep for 200ms)...');\n// In a real application, you might `await` this, but for demonstration, we just call it.\nsleepFunction(200);\nconsole.log('Sleep function called. Execution continues in JS thread.');\n\n// Await a promise if the sleepFunction were to return one\n// async function runAsync() {\n//   console.log('Calling truly async native function...');\n//   const asyncResult = await sleepFunctionAsync(200);\n//   console.log(`Async function completed after: ${asyncResult}ms`);\n// }\n// runAsync();","lang":"typescript","description":"Demonstrates how to import and call both synchronous and asynchronous functions exposed by the N-API native addon."},"warnings":[{"fix":"If intending to develop a `napi-rs` project, follow the template instructions (fork, rename). If seeking an ESLint plugin, install `eslint-plugin-barrel-files` instead.","message":"The package name `eslint-barrel-file-utils` is misleading. This package is primarily a template project for `napi-rs` native addons and does not contain any actual ESLint utility functions. Users seeking ESLint barrel file utilities should look for `eslint-plugin-barrel-files` (from the same author) or similar plugins.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Consult the `napi-rs` v2 to v3 migration guide for detailed instructions on updating `Cargo.toml`, `package.json` configuration, and Rust code.","message":"`napi-rs` v3 (released after `napi-rs` v2) introduced significant breaking changes in its CLI, configuration, and Rust API. Projects forked from this template that attempt to upgrade their `napi-rs` dependency to v3 will require code and configuration updates. Key changes include `napi.name` to `napi.binaryName`, `napi.triples` to `napi.targets`, and changes to `ThreadsafeFunction` usage.","severity":"breaking","affected_versions":">=3.0.0 (for `napi-rs` itself)"},{"fix":"Install the latest stable Rust toolchain via `rustup` as per the official Rust documentation. Ensure Node.js 10+ is also installed.","message":"While `napi-rs` simplifies native addon development, local development and custom builds still require a Rust toolchain (`rustup`) to be installed. Prebuilt binaries distributed via `optionalDependencies` on npm typically mitigate this for end-users, but developers modifying the Rust source will need a functional Rust environment.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"For optimal performance and correctness in `napi-rs` v2 projects, carefully manage `Buffer` and `TypedArray` ownership. Consider upgrading to `napi-rs` v3 and adopting its explicit `Reference<Buffer>` patterns for async operations to ensure zero-overhead data transfer and memory safety.","message":"When passing `Buffer` or `TypedArray` instances between JavaScript and Rust, `napi-rs` v2 (which this template likely uses as `eslint-barrel-file-utils` is version 0.0.15) might introduce unnecessary overhead by automatically creating references. `napi-rs` v3 addresses this by enforcing explicit `Reference<Buffer>` or `BufferRef` for async scenarios, but v2 projects might incur performance costs or encounter unsoundness if `&mut _` is used with async functions.","severity":"gotcha","affected_versions":"<3.0.0 (of `napi-rs` runtime)"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `npm install` (or `yarn install`) completed successfully. This error often indicates a problem during installation where the correct platform-specific optional dependency failed to download, or the native binary was not built for the target environment. Check npm logs for details or try cleaning `node_modules` and reinstalling. If developing, ensure `yarn build` was run to generate the local native addon.","cause":"The native binary for the current platform/architecture could not be found or loaded by Node.js.","error":"Error: Cannot find module 'eslint-barrel-file-utils/darwin-x64' or similar platform-specific module."},{"fix":"For Rust functions intended to be called asynchronously and not block the main thread, ensure they use `ThreadsafeFunction` or `Async` patterns provided by `napi-rs` to safely communicate results back to the main JavaScript thread. Avoid direct V8 API calls from background threads.","cause":"A native function that interacts with the V8 JavaScript engine (e.g., creating objects or manipulating the JS event loop) was called from a Rust thread that is not the main Node.js event loop thread.","error":"N-API Error: This function must be called on the main thread."},{"fix":"Verify the JavaScript types of arguments passed to native functions match the Rust function signatures (e.g., `i32` expects a number, `String` expects a string). Refer to the generated TypeScript type definitions for the correct function signatures.","cause":"A JavaScript argument passed to a Rust function did not match the expected type (e.g., passing a string where a number was expected).","error":"TypeError: 'argument' must be a number"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}