@wizhut_tech/wizjs 0.1.7 → 0.2.0

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_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__/package_exports.test.js

@@ -0,0 +1,79 @@
+const t = require('tap');
+const fs = require('fs');
+const path = require('path');
+
+const root = require('@wizhut_tech/wizjs');
+
+const PUBLIC_NAMESPACES = ['io', 'lang', 'math'];
+const SRC = path.join(__dirname, '..', 'src');
+
+
+function areasOf(namespace) {
+    return fs.readdirSync(path.join(SRC, namespace))
+        .filter((name) => name.endsWith('.js'))
+        .map((name) => name.slice(0, -3))
+        .sort();
+}
+
+
+t.test('exports/every public leaf module has a subpath', (t) => {
+    for (const namespace of PUBLIC_NAMESPACES) {
+        const areas = areasOf(namespace);
+        t.ok(areas.length > 0, `${namespace} has at least one area`);
+
+        for (const area of areas) {
+            const subpath = `@wizhut_tech/wizjs/${namespace}/${area}`;
+
+            t.equal(
+                require(subpath),
+                root[namespace][area],
+                `${subpath} is the same object as root.${namespace}.${area}`
+            );
+
+            t.equal(
+                require(`${subpath}.js`),
+                root[namespace][area],
+                `${subpath}.js resolves to the same object`
+            );
+        }
+    }
+
+    t.end();
+});
+
+
+t.test('exports/root entry point still resolves', (t) => {
+    t.equal(require('@wizhut_tech/wizjs'), root);
+    t.type(root.lang.collections.Counter, 'function');
+    t.type(root.exceptions.BadlyInitializedError, 'function');
+    t.end();
+});
+
+
+t.test('exports/internals stay private', (t) => {
+    t.throws(
+        () => require('@wizhut_tech/wizjs/internal/exceptions'),
+        { code: 'ERR_PACKAGE_PATH_NOT_EXPORTED' },
+        'src/internal is not reachable as a subpath'
+    );
+
+    t.throws(
+        () => require('@wizhut_tech/wizjs/src/lang/collections.js'),
+        { code: 'ERR_PACKAGE_PATH_NOT_EXPORTED' },
+        'the raw src/ layout is not part of the public surface'
+    );
+
+    t.throws(
+        () => require('@wizhut_tech/wizjs/lang/does-not-exist'),
+        { code: 'MODULE_NOT_FOUND' },
+        'an unknown area under a mapped namespace fails to resolve'
+    );
+
+    t.end();
+});
+
+
+t.test('exports/package.json is reachable', (t) => {
+    t.equal(require('@wizhut_tech/wizjs/package.json').name, '@wizhut_tech/wizjs');
+    t.end();
+});

package/package.json

@@ -7,6 +7,19 @@
   "devDependencies": {
     "tap": "21.7.5"
   },
+  "engines": {
+    "node": ">=14.13.0"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./io/*": "./src/io/*.js",
+    "./io/*.js": "./src/io/*.js",
+    "./lang/*": "./src/lang/*.js",
+    "./lang/*.js": "./src/lang/*.js",
+    "./math/*": "./src/math/*.js",
+    "./math/*.js": "./src/math/*.js",
+    "./package.json": "./package.json"
+  },
   "homepage": "https://github.com/wizhut/wizjs#readme",
   "keywords": [
     "javascript",
@@ -24,5 +37,5 @@
   "scripts": {
     "test": "tap run"
   },
-  "version": "0.1.7"
+  "version": "0.2.0"
 }

package/readme.md

@@ -27,10 +27,25 @@ Use by importing:
 }
 ```
 
-You can also import individual functions like the following snippet:
+You can also import individual functions from that root object:
 
 `const { lang: { checks : { isNil } } }  = require('@wizhut_tech/wizjs');`
 
+Or require a single namespace area directly, which keeps the destructuring flat
+when you need helpers from more than one area:
+
+```js
+const { isNil } = require('@wizhut_tech/wizjs/lang/checks');
+const { Counter } = require('@wizhut_tech/wizjs/lang/collections');
+const { clamp } = require('@wizhut_tech/wizjs/math/numbers');
+```
+
+Every area listed below is reachable as `@wizhut_tech/wizjs/<namespace>/<area>`,
+and resolves to the very same object the root import exposes, so the two styles
+mix freely. The subpath form needs Node 14.13 or newer. Library internals (under
+`src/internal/`) are deliberately not reachable this way — `BadlyInitializedError`
+is re-exported from the root import instead.
+
 ### I/O
 
 * **Files** utility functions ... [[docs](docs/io_files.md)]

package/src/io/files.js

@@ -3,7 +3,7 @@ const fs = require('fs').promises;
 
 async function loadFully(filename) {
     try {
-        const data = await fs.readFile(filename, 'utf8');
+        return await fs.readFile(filename, 'utf8');
     } catch (err) {
         return null;
     }

package/CLAUDE.md

@@ -1,56 +0,0 @@
-# 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).