@wizhut_tech/wizjs 0.1.5 → 0.2.0

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/__tests__/internal_exceptions.test.js

@@ -0,0 +1,29 @@
+const t = require('tap');
+
+const { BadlyInitializedError } = require('../src/internal/exceptions.js');
+const root = require('@wizhut_tech/wizjs');
+
+
+t.test('exceptions/BadlyInitializedError behaves like an Error', (t) => {
+    const err = new BadlyInitializedError('not ready');
+
+    t.type(err, Error, 'extends Error');
+    t.type(err, BadlyInitializedError);
+    t.equal(err.message, 'not ready');
+    t.ok(err.stack, 'carries a stack');
+    t.end();
+});
+
+
+t.test('exceptions/BadlyInitializedError ignores trailing arguments', (t) => {
+    const err = new BadlyInitializedError('only the message', 'extra', 42);
+
+    t.equal(err.message, 'only the message');
+    t.end();
+});
+
+
+t.test('exceptions/BadlyInitializedError is the one the root import exposes', (t) => {
+    t.equal(root.exceptions.BadlyInitializedError, BadlyInitializedError);
+    t.end();
+});

package/__tests__/io_files.test.js

@@ -0,0 +1,41 @@
+const t = require('tap');
+const path = require('path');
+
+const { loadFully } = require('../src/io/files.js');
+
+
+t.test('files/loadFully returns null for a file that is not there', async (t) => {
+    const missing = path.join(t.testdir(), 'no-such-file.txt');
+
+    t.equal(await loadFully(missing), null);
+});
+
+
+t.test('files/loadFully returns null when the path is a directory', async (t) => {
+    const dir = t.testdir({ 'sub': {} });
+
+    t.equal(await loadFully(path.join(dir, 'sub')), null);
+});
+
+
+t.test('files/loadFully returns the whole file as text', async (t) => {
+    const dir = t.testdir({ 'hello.txt': 'contents\n' });
+
+    t.equal(await loadFully(path.join(dir, 'hello.txt')), 'contents\n');
+});
+
+
+t.test('files/loadFully returns an empty string for an empty file', async (t) => {
+    const dir = t.testdir({ 'empty.txt': '' });
+
+    t.equal(await loadFully(path.join(dir, 'empty.txt')), '',
+        'an empty file is distinguishable from a failed read');
+});
+
+
+t.test('files/loadFully preserves multi-line and unicode content', async (t) => {
+    const body = 'first\nsecond\n\u03b1\u03b2\u03b3\n';
+    const dir = t.testdir({ 'multi.txt': body });
+
+    t.equal(await loadFully(path.join(dir, 'multi.txt')), body);
+});

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_flow.test.js

@@ -0,0 +1,49 @@
+const t = require('tap');
+
+const { if_exception } = require('../src/lang/flow.js');
+
+
+t.test('flow/if_exception runs the success branch', (t) => {
+    const calls = [];
+
+    if_exception(
+        () => calls.push('body'),
+        () => calls.push('ok'),
+        () => calls.push('failed')
+    );
+
+    t.same(calls, ['body', 'ok']);
+    t.end();
+});
+
+
+t.test('flow/if_exception runs the failure branch with the error', (t) => {
+    const calls = [];
+    const boom = new Error('boom');
+    let seen = null;
+
+    if_exception(
+        () => { calls.push('body'); throw boom; },
+        () => calls.push('ok'),
+        (error) => { calls.push('failed'); seen = error; }
+    );
+
+    t.same(calls, ['body', 'failed'], 'the success callback is skipped');
+    t.equal(seen, boom, 'the thrown error is handed to the failure callback');
+    t.end();
+});
+
+
+t.test('flow/if_exception catches a throw from the success callback', (t) => {
+    const boom = new Error('from fn_noexc');
+    let seen = null;
+
+    if_exception(
+        () => {},
+        () => { throw boom; },
+        (error) => { seen = error; }
+    );
+
+    t.equal(seen, boom, 'fn_noexc runs inside the same try block');
+    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();
+});