js-bunch

A modern, type-safe utility belt for Node.js and the browser. Tree-shakable, zero runtime dependencies, dual ESM/CJS, ships with full TypeScript types.

npm install js-bunch

import { uniq, drop, todayWeather } from 'js-bunch';

uniq([1, 2, 1, 3]);   // [1, 2, 3]
drop([1, 2, 3], 2);   // [3]

const info = await todayWeather();
console.log(info.city, info.country_name);

Why js-bunch?

• Tiny. Tree-shakable ESM build — import only what you use.
• Typed. First-class TypeScript with strict null-safety on every helper.
• Zero dependencies. No axios, no lodash — just modern platform APIs.
• Works everywhere. Node.js 18+, Deno, Bun, browsers, Workers.
• Dual package. Ships ESM and CJS side by side; use either freely.

Installation

npm install js-bunch
# or
pnpm add js-bunch
# or
yarn add js-bunch
# or
bun add js-bunch

Usage

Full import

import { uniq, union, todayWeather } from 'js-bunch';

Sub-path imports (smaller bundle)

import { uniq, drop } from 'js-bunch/array';
import { todayWeather } from 'js-bunch/weather';

CommonJS

const { uniq, drop } = require('js-bunch');

API

Array helpers (js-bunch/array)

| Function | Description | | --- | --- | | drop(array, n?) | Drop the first n (default 1) elements. | | findIndex(array, value \| predicate) | First index matching value or predicate, else -1. | | first(array) | First element, or undefined. | | indexOf(array, value, fromIndex?) | First index using SameValueZero (matches NaN). | | remove(array, value \| predicate) | New array with matching elements removed (immutable). | | reverse(array) | Reversed copy — does not mutate the input. | | slice(array, start?, end?) | Null-safe Array.prototype.slice. | | uniq(array) | Unique values, first-seen order. | | sortedUniq(array, compareFn?) | Sorted, deduplicated copy. | | union(...arrays) | Concatenate any number of arrays (preserves duplicates). | | unionUniq(...arrays) | Concatenate and deduplicate. |

import { drop, uniq, sortedUniq, unionUniq, remove } from 'js-bunch/array';

drop([1, 2, 3], 2);              // [3]
uniq([1, 2, 1, 3, 2]);           // [1, 2, 3]
sortedUniq([3, 1, 2, 1], (a, b) => a - b); // [1, 2, 3]
unionUniq([1, 2], [2, 3]);       // [1, 2, 3]
remove([1, 2, 3, 4], (x) => x % 2 === 0); // [1, 3]

todayWeather(options?)

Returns IP-based geolocation info for the caller's public IP via ipapi.co.

Note: despite the historical name, the endpoint returns geolocation data (city, country, timezone, etc.), not meteorological data. The name is preserved for backwards compatibility with v0.x.

import { todayWeather } from 'js-bunch/weather';

const info = await todayWeather();
//   ^? IpInfo — typed response

// With timeout
const fast = await todayWeather({ timeoutMs: 3_000 });

// With AbortSignal
const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 500);
await todayWeather({ signal: ctrl.signal });

// With custom endpoint (e.g., for proxies/tests)
await todayWeather({ endpoint: 'https://my-proxy.example.com/ip' });

Returned fields include ip, city, region, country_name, country_code, latitude, longitude, timezone, currency, and more. See IpInfo for the full type.

TypeScript

Every helper is fully typed with generics where appropriate. Null/undefined inputs are explicitly handled.

import { first } from 'js-bunch';

const x = first([1, 2, 3]); // x: number | undefined
const y = first<string>([]);// y: string | undefined

Migrating from v0.x

1.0.0 is a full rewrite. The exported API is the same, with these compatible improvements:

• first(empty) now returns undefined (was null). Use ?? null if you depend on the old shape.
• reverse() no longer mutates the input — it returns a reversed copy.
• remove() and findIndex() accept a predicate function in addition to a value.
• union(a, b) now accepts any number of arrays: union(a, b, c, d).
• todayWeather() returns the same payload but now supports signal, timeoutMs, and endpoint options.
• The package no longer depends on axios. Node.js 18+ is required (native fetch).

Requirements

• Node.js 18+ (uses native fetch for the weather helper)
• Or any modern browser / Deno / Bun / Cloudflare Workers

Contributing

Issues and PRs welcome at github.com/arqam-dev/js-bunch.

git clone https://github.com/arqam-dev/js-bunch.git
cd js-bunch
npm install
npm test
npm run build

License

MIT © Muhammad Arqam