necessary

library0.4.3jsnpmunverified

Necessary is a JavaScript utility library offering a curated collection of functions inspired by larger libraries like Lodash and Async. It aims to provide essential utilities with a relatively small footprint and transparent implementations, particularly for asynchronous operations, to aid debugging. The library, currently at version 17.1.8, features a clear separation of concerns, with distinct utility collections for browser-only environments (e.g., Ajax), Node.js-only environments (e.g., File System, Shell), and universal utilities usable in both (e.g., Array, String, Asynchronous). It exports utility collections as plain JavaScript objects, from which individual functions can be destructured. The project appears actively maintained with regular updates, although a specific release cadence isn't explicitly stated. Key differentiators include its modular structure, explicit environment targeting, and a focus on simplicity over feature breadth.

http-networking data

npm install necessary

github ↗package ↗

INSTALL

IMPORT

SIG · NECESSARY

necessary

http-networkingjavascriptv0.4.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

arrayUtilities

✓ import { arrayUtilities } from 'necessary';

✗ import arrayUtilities from 'necessary';

The library exports collections of utilities as named exports, not a default export. Individual functions are then destructured from these collection objects.

first

✓ import { arrayUtilities } from 'necessary'; const { first } = arrayUtilities;

✗ import { first } from 'necessary';

Individual utility functions like `first` are properties of their respective utility collection objects (e.g., `arrayUtilities`), not direct top-level named exports of the `necessary` package itself.

fileSystemUtilities

✓ const { fileSystemUtilities } = require('necessary');

✗ import { fileSystemUtilities } from 'necessary';

For Node.js environments where CommonJS is prevalent or required, use `require()` for the utility collections. This specific collection is Node.js-only.

get

✓ import { ajaxUtilities } from 'necessary'; const { get } = ajaxUtilities;

✗ import { get } from 'necessary';

`get` is a function within the `ajaxUtilities` collection, which is browser-only. It is not a direct named export.

This example demonstrates how to import and use universal array utilities and Node.js-specific file system utilities, including creating and reading files/directories.

import { arrayUtilities, fileSystemUtilities } from 'necessary'; import path from 'path'; // Standard Node.js module import fs from 'fs/promises'; // Standard Node.js module const { first, last, unique } = arrayUtilities; const { isDirectory, readFile } = fileSystemUtilities; async function runExample() { const numbers = [1, 2, 2, 3, 4, 4, 5]; console.log('Original array:', numbers); console.log('First element:', first(numbers)); console.log('Last element:', last(numbers)); console.log('Unique elements:', unique(numbers)); const tempDir = path.join(process.cwd(), 'temp_necessary_test'); const tempFile = path.join(tempDir, 'test.txt'); try { await fs.mkdir(tempDir, { recursive: true }); await fs.writeFile(tempFile, 'Hello from Necessary!'); console.log(`Checking if '${tempDir}' is a directory...`); const dirCheck = await isDirectory(tempDir); console.log(`Is directory: ${dirCheck}`); console.log(`Reading content from '${tempFile}'...`); const content = await readFile(tempFile); console.log(`File content: ${content.toString()}`); } catch (error) { console.error('Error during file system operations:', error.message); } finally { // Clean up await fs.rm(tempDir, { recursive: true, force: true }); console.log('Cleaned up temporary directory.'); } } runExample();

Debug

Known issues

gotchaUtilities are strictly partitioned for 'Node-only' and 'Browser-only' environments. Attempting to use a Node-specific utility (e.g., `fileSystemUtilities`, `shellUtilities`) in a browser environment, or a browser-specific utility (e.g., `ajaxUtilities`) in Node.js, will result in runtime errors.

fix

Ensure you are using the correct set of utilities for your target environment. Bundlers like Webpack or Rollup may need configuration to handle environment-specific code splitting.

affects: >=1.0.0

gotchaThe library exports collections of utilities as named objects (e.g., `arrayUtilities`). Individual functions are properties of these objects. Direct named imports of functions (e.g., `import { first } from 'necessary'`) will fail.

fix

Always import the utility collection first, then destructure the desired functions: `import { arrayUtilities } from 'necessary'; const { first } = arrayUtilities;`

affects: >=1.0.0

gotchaWhile the README shows both ESM `import` and CommonJS `require()` examples, be mindful of your project's module system configuration. Mixing `import` for `necessary` with `require()` for other modules in an ESM project (or vice-versa) can lead to unexpected behavior or build errors without proper transpilation.

fix

Standardize on either ESM `import` or CommonJS `require()` across your project. If using ESM, ensure your `package.json` specifies `"type": "module"` and configure your bundler/transpiler accordingly.

affects: >=1.0.0

gotchaThe README provides examples where `uri` arguments for AJAX functions must include a leading forward slash, and `host` arguments should not have a trailing one. Inconsistent application of this rule can lead to incorrect request URLs and failed HTTP calls.

fix

Strictly adhere to the `host` (no trailing slash) and `uri` (leading slash) format for `ajaxUtilities` to ensure correct URL construction.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require()` in an ECMAScript Module (ESM) context without proper configuration.

fix

If your project is ESM-based (e.g., `"type": "module"` in `package.json`), use `import` statements instead: `import { arrayUtilities } from 'necessary';`. If you truly need `require()` in an ESM file, consider dynamic `import()` or review your project's module configuration.

TypeError: Cannot read properties of undefined (reading 'get')

Attempting to use a specific utility function directly imported from 'necessary' or from an incorrectly imported utility collection.

fix

Ensure you are importing the correct utility collection object (e.g., `ajaxUtilities`) and then destructuring the function from it: `import { ajaxUtilities } from 'necessary'; const { get } = ajaxUtilities;`

TypeError: fileSystemUtilities.isDirectory is not a function (or similar for other Node/Browser specific functions)

Attempting to call a Node.js-only function (`isDirectory`) in a browser environment, or a browser-only function (e.g., `ajaxUtilities.get`) in a Node.js environment.

fix

Verify your execution environment. If in a browser, only use browser-safe or universal utilities. If in Node.js, only use Node-safe or universal utilities. Implement environment-specific code paths if necessary.

Upgrade

Version history

0.4.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/djalbat/necessary ↗

packagehttps://www.npmjs.com/package/necessary ↗