@wizhut_tech/wizjs 0.1.4 → 0.1.7

package/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release
+
+# Tag-driven: pushing v<x.y.z> runs the suite, publishes @wizhut_tech/wizjs to
+# npm and opens a GitHub release. Cut one with:
+#   npm version patch && git push --follow-tags
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write # gh release create
+  id-token: write # npm trusted publishing (OIDC)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # --generate-notes diffs against the previous tag
+
+      # Do not set registry-url here: setup-node would write an .npmrc with an
+      # empty _authToken and that short-circuits npm OIDC trusted publishing
+      # (the CLI then 404s the PUT as if the package did not exist).
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+
+      # `npm version` keeps these in step; a hand-made tag might not.
+      - name: Check the tag matches package.json
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(node -p "require('./package.json').version")"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match package.json version $pkg"
+            exit 1
+          fi
+
+      - run: npm ci
+      - run: npm test
+
+      # Trusted publishing: npmjs.com is configured to trust this repo's
+      # release.yml, so there is no NPM_TOKEN — the OIDC id-token is the
+      # credential, and npm attaches a provenance attestation. Needs npm
+      # >= 11.5.1, hence the upgrade.
+      - name: Publish to npm
+        run: |
+          npm install -g npm@latest
+          npm publish --access public
+
+      - name: Publish the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "wizjs $GITHUB_REF_NAME" \
+            --generate-notes

package/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`@wizhut_tech/wizjs` is a small, curated JavaScript utility library — Python idioms and selected stdlib helpers (`itertools`, `functools`, `collections`) for everyday JS, explicitly *not* trying to be lodash. Helpers are grouped into top-level namespaces (`io`, `lang`, `math`) with focused sub-areas under each. It is plain JavaScript (no TypeScript), CommonJS (no `type: "module"`, no build step), and ships its source directly to npm. It pulls in no runtime dependencies; the only third-party use is Node's built-in `fs` in `io/files`, so anything outside that namespace is runtime-agnostic.
+
+## Commands
+
+```sh
+npm install            # install devDependencies (only `tap`)
+npm test               # full suite — runs `tap run` over __tests__/
+npx tap __tests__/lang_arrays.test.js   # run a SINGLE test file
+```
+
+There is **no build, lint, or typecheck step** — `test` is the only npm script. The test runner is [`tap`](https://node-tap.org) (v21). Tests live in `__tests__/`, one file per namespace sub-area, named `<namespace>_<area>.test.js` (e.g. `lang_arrays.test.js`, `math_numbers.test.js`).
+
+Publishing goes to the scoped package `@wizhut_tech/wizjs` and is tag-driven, from CI: `npm version patch` then `git push --follow-tags`, and the `v<x.y.z>` tag triggers [`.github/workflows/release.yml`](.github/workflows/release.yml) — tag/`package.json` check, `npm ci && npm test`, `npm publish --access public`, GitHub release. Authentication is npm OIDC trusted publishing, so there is no token anywhere; don't publish from a laptop, as hand-published versions lose the provenance attestation. There is no `files` allowlist or `.npmignore`, so the published tarball includes `index.js` + `src/`. The repo declares the MIT license in `package.json` but currently has **no LICENSE file**.
+
+## Architecture
+
+The single entry point is `index.js`. It `require`s each leaf module from `src/` and composes them into one nested object — the entire public API surface:
+
+```
+io.files          → src/io/files.js        (loadFully)
+lang.arrays       → src/lang/arrays.js      (compact, accumulate, Operator, unique, chunk, flatten)
+lang.singleton    → src/lang/singleton.js   (singleton, getInstance)
+lang.flow         → src/lang/flow.js        (if_exception)
+lang.checks       → src/lang/checks.js      (isNil, isArray, isObject, isString, isNumber, isBoolean, isFunction, isInteger, isEmpty)
+lang.functools    → src/lang/functools.js   (reflexive, partial, compose, once, memoize, cache, reduce)
+lang.itertools    → src/lang/itertools.js   (count, repeat, cycle, chain, take, zip, range, enumerate, islice, takewhile, dropwhile, filterfalse, zip_longest, product, groupby, starmap, batched, pairwise, compress)
+lang.objects      → src/lang/objects.js     (pick, omit, get)
+lang.collections  → src/lang/collections.js (Counter, DefaultDict)
+math.numbers      → src/math/numbers.js     (toInteger, toNumber, clamp, mod)
+exceptions        → src/internal/exceptions.js (BadlyInitializedError)
+```
+
+Each leaf module is a flat `module.exports = { ... }` of functions (plus the occasional class, e.g. `Operator`). The namespace objects in `index.js` are just references to those `module.exports`, so whatever a leaf exports is reachable both as `wizjs.lang.arrays.<name>` and via destructuring (`const { lang: { arrays: { compact } } } = require('@wizhut_tech/wizjs')`).
+
+Directory layout mirrors the namespace path exactly: `src/<top-namespace>/<area>.js`. `src/internal/` holds non-public building blocks (currently just `exceptions.js`); its contents are surfaced selectively — `index.js` re-exports `BadlyInitializedError` under the top-level `exceptions` key rather than mounting the whole module.
+
+Where a helper belongs:
+- I/O / filesystem / external resources → `src/io/`
+- General language utilities → `src/lang/` (`checks` = type/predicate tests, `arrays` = array ops, `flow` = control-flow wrappers, `functools` = function helpers, `itertools` = lazy generators, `objects` = plain-object pick/omit/get, `collections` = Python `Counter` / `DefaultDict`, `singleton` = the singleton hack)
+- Numeric helpers → `src/math/`
+- Shared internals not meant as public API → `src/internal/`
+
+Cross-module reuse is direct relative `require` (e.g. `arrays.js` and `numbers.js` both import `isNil` from `lang/checks.js`; `itertools.js` imports `toInteger` from `math/numbers.js`).
+
+## Conventions
+
+- **Module format:** CommonJS only — `require(...)` / `module.exports`. No ESM, no transpilation.
+- **Naming:** functions are camelCase (`isNil`, `loadFully`, `toInteger`); Python stdlib names are kept as in Python (`if_exception`, `takewhile`, `zip_longest`, `groupby`). Classes are PascalCase (`Operator`, `BadlyInitializedError`, `Counter`, `DefaultDict`). Lazy/iterator helpers in `itertools` are generator functions.
+- **Adding a helper to an existing area:** write the function in the matching `src/<ns>/<area>.js`, add it to that file's `module.exports`, and add cases to the corresponding `__tests__/<ns>_<area>.test.js`. It becomes available automatically since `index.js` references the whole `module.exports`.
+- **Adding a new area or namespace:** create `src/<ns>/<area>.js`, then `require` it in `index.js` and mount it under the right namespace object. Add a `docs/<ns>_<area>.md` page and a matching `__tests__/<ns>_<area>.test.js`. Each namespace sub-area has a doc page under `docs/` linked from `readme.md` (lowercase filename).

package/__tests__/lang_arrays.test.js

@@ -1,6 +1,6 @@
 const t = require('tap');
 
-const { compact, accumulate, Operator } = require('../src/lang/arrays.js');
+const { compact, accumulate, Operator, unique, chunk, flatten } = require('../src/lang/arrays.js');
 
 
 t.test('arrays/compact', (t) => {
@@ -22,4 +22,46 @@ t.test('arrays/accumulate', (t) => {
     t.equal(accumulate(arr, Operator.multiply, 0), 0);
     t.equal(accumulate(arr, Operator.divide, 0), 0);
     t.end();
-});
+});
+
+
+t.test('arrays/unique', (t) => {
+    t.match(unique([1, 2, 2, 3, 1]), [1, 2, 3]);
+    t.match(unique(['a', 'b', 'a']), ['a', 'b']);
+    t.match(unique([NaN, NaN, 1]), [NaN, 1]);
+    t.match(unique([0, false, 0, false]), [0, false]);
+    t.match(unique([]), []);
+    t.match(unique(null), []);
+    t.match(unique(undefined), []);
+
+    const a = { id: 1 };
+    const b = { id: 1 };
+    t.match(unique([a, b, a]), [a, b]);
+    t.end();
+});
+
+
+t.test('arrays/chunk', (t) => {
+    t.match(chunk([1, 2, 3, 4, 5], 2), [[1, 2], [3, 4], [5]]);
+    t.match(chunk([1, 2, 3], 3), [[1, 2, 3]]);
+    t.match(chunk([1, 2, 3], 5), [[1, 2, 3]]);
+    t.match(chunk([], 2), []);
+    t.match(chunk(null, 2), []);
+    t.match(chunk(undefined, 2), []);
+    t.match(chunk([1, 2, 3], 0), []);
+    t.match(chunk([1, 2, 3], -1), []);
+    t.match(chunk([1, 2, 3], '2'), [[1, 2], [3]]);
+    t.end();
+});
+
+
+t.test('arrays/flatten', (t) => {
+    t.match(flatten([1, [2, 3], 4]), [1, 2, 3, 4]);
+    t.match(flatten([1, [2, [3]], 4]), [1, 2, [3], 4]);
+    t.match(flatten([1, 2, 3]), [1, 2, 3]);
+    t.match(flatten([]), []);
+    t.match(flatten(null), []);
+    t.match(flatten(undefined), []);
+    t.match(flatten([[], [1], 2]), [1, 2]);
+    t.end();
+});

package/__tests__/lang_checks.test.js

@@ -1,6 +1,6 @@
 const t = require('tap');
 
-const { isNil, isArray, isObject, isNumber, isString } = require('../src/lang/checks.js');
+const { isNil, isArray, isObject, isNumber, isString, isBoolean, isFunction, isInteger, isEmpty } = require('../src/lang/checks.js');
 
 
 
@@ -53,4 +53,65 @@ t.test('checks/isString', (t) => {
     t.equal(isString(1.1), false);
     t.equal(isString('misc'), true);
     t.end();
-})
+});
+
+t.test('checks/isBoolean', (t) => {
+    t.equal(isBoolean(true), true);
+    t.equal(isBoolean(false), true);
+    t.equal(isBoolean(null), false);
+    t.equal(isBoolean(undefined), false);
+    t.equal(isBoolean(0), false);
+    t.equal(isBoolean(1), false);
+    t.equal(isBoolean('true'), false);
+    t.equal(isBoolean({}), false);
+    t.end();
+});
+
+t.test('checks/isFunction', (t) => {
+    t.equal(isFunction(function () {}), true);
+    t.equal(isFunction(() => 1), true);
+    t.equal(isFunction(async () => 1), true);
+    t.equal(isFunction(function* () {}), true);
+    t.equal(isFunction(class Foo {}), true);
+    t.equal(isFunction(null), false);
+    t.equal(isFunction(undefined), false);
+    t.equal(isFunction(1), false);
+    t.equal(isFunction('fn'), false);
+    t.equal(isFunction({}), false);
+    t.end();
+});
+
+t.test('checks/isInteger', (t) => {
+    t.equal(isInteger(1), true);
+    t.equal(isInteger(0), true);
+    t.equal(isInteger(-4), true);
+    t.equal(isInteger(1.0), true);
+    t.equal(isInteger(1.1), false);
+    t.equal(isInteger(NaN), false);
+    t.equal(isInteger(Infinity), false);
+    t.equal(isInteger('1'), false);
+    t.equal(isInteger(null), false);
+    t.equal(isInteger(undefined), false);
+    t.equal(isInteger(true), false);
+    t.end();
+});
+
+t.test('checks/isEmpty', (t) => {
+    t.equal(isEmpty(null), true);
+    t.equal(isEmpty(undefined), true);
+    t.equal(isEmpty(''), true);
+    t.equal(isEmpty([]), true);
+    t.equal(isEmpty({}), true);
+    t.equal(isEmpty(new Map()), true);
+    t.equal(isEmpty(new Set()), true);
+
+    t.equal(isEmpty(' '), false);
+    t.equal(isEmpty([0]), false);
+    t.equal(isEmpty({ a: 1 }), false);
+    t.equal(isEmpty(new Map([['a', 1]])), false);
+    t.equal(isEmpty(new Set([1])), false);
+    t.equal(isEmpty(0), false);
+    t.equal(isEmpty(false), false);
+    t.equal(isEmpty(() => {}), false);
+    t.end();
+});

package/__tests__/lang_collections.test.js

@@ -0,0 +1,90 @@
+const t = require('tap');
+
+const { Counter, DefaultDict } = require('../src/lang/collections.js');
+
+
+t.test('collections/Counter', (t) => {
+    const fromString = new Counter('aab');
+    t.equal(fromString.get('a'), 2);
+    t.equal(fromString.get('b'), 1);
+    t.equal(fromString.get('z'), 0);
+    t.equal(fromString.total(), 3);
+    t.equal(fromString.size, 2);
+    t.match([...fromString], ['a', 'b']);
+    t.match([...fromString.keys()], ['a', 'b']);
+    t.match([...fromString.values()], [2, 1]);
+    t.match([...fromString.entries()], [['a', 2], ['b', 1]]);
+    t.match([...fromString.elements()], ['a', 'a', 'b']);
+
+    const fromObj = new Counter({ a: 4, b: 2 });
+    t.equal(fromObj.get('a'), 4);
+    t.match(fromObj.mostCommon(1), [['a', 4]]);
+    t.match(fromObj.mostCommon(), [['a', 4], ['b', 2]]);
+    t.match(fromObj.mostCommon(0), []);
+
+    const fromArr = new Counter([1, 1, 2]);
+    t.equal(fromArr.get(1), 2);
+    fromArr.add(1);
+    t.equal(fromArr.get(1), 3);
+    fromArr.add(3, 5);
+    t.equal(fromArr.get(3), 5);
+    fromArr.set(2, 0);
+    t.equal(fromArr.get(2), 0);
+    t.ok(fromArr.delete(2));
+    t.equal(fromArr.get(2), 0);
+
+    const zeros = new Counter();
+    zeros.set('gone', 0);
+    zeros.set('neg', -1);
+    zeros.set('keep', 2);
+    t.match([...zeros.elements()], ['keep', 'keep']);
+
+    const fromMap = new Counter(new Map([['x', 3], ['y', 1]]));
+    t.equal(fromMap.get('x'), 3);
+
+    const copy = new Counter(fromString);
+    t.equal(copy.get('a'), 2);
+    copy.add('a');
+    t.equal(fromString.get('a'), 2);
+
+    const empty = new Counter();
+    t.equal(empty.total(), 0);
+    t.match([...empty.elements()], []);
+
+    const nan = new Counter([NaN, NaN]);
+    t.equal(nan.get(NaN), 2);
+    t.end();
+});
+
+
+t.test('collections/DefaultDict', (t) => {
+    const groups = new DefaultDict(Array);
+    groups.get('a').push(1);
+    groups.get('a').push(2);
+    groups.get('b').push(3);
+    t.match(groups.get('a'), [1, 2]);
+    t.match(groups.get('b'), [3]);
+    t.equal(groups.size, 2);
+    t.ok(groups.has('a'));
+    t.equal(groups.peek('missing', 'nope'), 'nope');
+    t.match(groups.peek('a'), [1, 2]);
+    t.equal(groups.has('missing'), false);
+
+    groups.set('c', [9]);
+    t.match(groups.get('c'), [9]);
+    t.ok(groups.delete('c'));
+    t.equal(groups.has('c'), false);
+
+    t.match([...groups.keys()], ['a', 'b']);
+    t.equal([...groups.values()].length, 2);
+    t.equal([...groups.entries()].length, 2);
+
+    const lists = new DefaultDict(() => []);
+    lists.get('k').push('x');
+    t.match(lists.get('k'), ['x']);
+
+    const noFactory = new DefaultDict();
+    t.equal(noFactory.get('x'), undefined);
+    t.equal(noFactory.has('x'), false);
+    t.end();
+});

package/__tests__/lang_functools.test.js

@@ -1,6 +1,6 @@
 const t = require('tap');
 
-const { reflexive } = require('../src/lang/functools.js');
+const { reflexive, partial, compose, once, memoize, cache, reduce } = require('../src/lang/functools.js');
 
 
 t.test('functools/reflexive', (t) => {
@@ -9,4 +9,125 @@ t.test('functools/reflexive', (t) => {
     t.equal(reflexive('abcde'), 'abcde');
     t.equal(reflexive(2.1), 2.1);
     t.end();
-});
+});
+
+
+t.test('functools/partial', (t) => {
+    const add = (a, b, c) => a + b + c;
+    const add10 = partial(add, 10);
+    t.equal(add10(1, 2), 13);
+
+    const add10and20 = partial(add, 10, 20);
+    t.equal(add10and20(3), 33);
+
+    const greet = function (greeting, name) {
+        return `${greeting} ${name}, ${this.title}`;
+    };
+    const hello = partial(greet, 'hello');
+    t.equal(hello.call({ title: 'Dr' }, 'Ada'), 'hello Ada, Dr');
+    t.end();
+});
+
+
+t.test('functools/compose', (t) => {
+    const inc = (n) => n + 1;
+    const double = (n) => n * 2;
+    t.equal(compose(double, inc)(3), 8);
+    t.equal(compose(inc, double)(3), 7);
+    t.equal(compose(inc)(3), 4);
+    t.equal(compose()(3), 3);
+
+    const first = (...args) => args.join('-');
+    const wrap = (s) => `[${s}]`;
+    t.equal(compose(wrap, first)('a', 'b'), '[a-b]');
+    t.end();
+});
+
+
+t.test('functools/once', (t) => {
+    let calls = 0;
+    const fn = (x) => {
+        calls += 1;
+        return x * 2;
+    };
+    const onceFn = once(fn);
+
+    t.equal(onceFn(4), 8);
+    t.equal(onceFn(9), 8);
+    t.equal(calls, 1);
+    t.end();
+});
+
+
+t.test('functools/memoize', (t) => {
+    let calls = 0;
+    const fn = (a, b) => {
+        calls += 1;
+        return a + b;
+    };
+    const mem = memoize(fn);
+
+    t.equal(mem(1, 2), 3);
+    t.equal(mem(1, 2), 3);
+    t.equal(calls, 1);
+    t.equal(mem(1, 3), 4);
+    t.equal(calls, 2);
+
+    // different arity is a different cache entry
+    t.equal(mem(1, 2, undefined), 3);
+    t.equal(calls, 3);
+
+    // NaN is a valid key (SameValueZero)
+    let nanCalls = 0;
+    const nanFn = memoize((n) => {
+        nanCalls += 1;
+        return n;
+    });
+    t.ok(Number.isNaN(nanFn(NaN)));
+    t.ok(Number.isNaN(nanFn(NaN)));
+    t.equal(nanCalls, 1);
+
+    // throws are not cached
+    let throws = 0;
+    const boom = memoize((ok) => {
+        throws += 1;
+        if (!ok) {
+            throw new Error('nope');
+        }
+        return 'ok';
+    });
+    t.throws(() => boom(false));
+    t.throws(() => boom(false));
+    t.equal(throws, 2);
+    t.equal(boom(true), 'ok');
+    t.equal(boom(true), 'ok');
+    t.equal(throws, 3);
+
+    // custom resolver
+    let resolved = 0;
+    const byName = memoize((obj) => {
+        resolved += 1;
+        return obj.v;
+    }, (obj) => obj.id);
+    t.equal(byName({ id: 1, v: 10 }), 10);
+    t.equal(byName({ id: 1, v: 99 }), 10);
+    t.equal(resolved, 1);
+
+    mem.cache.clear();
+    t.equal(mem(1, 2), 3);
+    t.equal(calls, 4);
+    t.equal(cache, memoize);
+    t.end();
+});
+
+
+t.test('functools/reduce', (t) => {
+    t.equal(reduce((a, b) => a + b, [1, 2, 3, 4]), 10);
+    t.equal(reduce((a, b) => a + b, [1, 2, 3, 4], 10), 20);
+    t.equal(reduce((a, b) => a + b, [], 0), 0);
+    t.equal(reduce((a, b) => a * b, (function* () { yield 2; yield 3; yield 4; })()), 24);
+    t.throws(() => reduce((a, b) => a + b, []));
+    t.throws(() => reduce((a, b) => a + b, null));
+    t.equal(reduce((a, b) => a + b, null, 5), 5);
+    t.end();
+});