@wizhut_tech/wizjs 0.1.4 → 0.1.5

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# 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 — "simple but useful hacks for everyday programming," 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 is plain npm (`npm publish`) to the scoped package `@wizhut_tech/wizjs`. There is no `files` allowlist or `.npmignore`, so the published tarball includes `index.js` + `src/`. Releases are cut by bumping `version` in `package.json` (recent history shows dedicated `version => x.y.z` commits). 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)
+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)
+lang.functools    → src/lang/functools.js   (reflexive)
+lang.itertools    → src/lang/itertools.js   (count, repeat)
+math.numbers      → src/math/numbers.js     (toInteger)
+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, `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`); some predates/control-flow names use snake_case (`if_exception`). Classes are PascalCase (`Operator`, `BadlyInitializedError`). 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_itertools.test.js

@@ -32,5 +32,11 @@ t.test('itertools/repeat', (t) => {
     t.equal(repeatGenTwo.next().value, 15);
     t.equal(repeatGenTwo.next().value, 15);
 
+    // negative times is clamped to 0, i.e. behaves like eternal repeat
+    const repeatGenThree = repeat(7, -3);
+    t.equal(repeatGenThree.next().value, 7);
+    t.equal(repeatGenThree.next().value, 7);
+    t.equal(repeatGenThree.return().done, true);
+
     t.end();
 });

package/__tests__/lang_singleton.test.js

@@ -19,5 +19,23 @@ t.test('singleton/simple-tests', async (t) => {
     singleton('null-wrapper', async () => null);
     t.equal(await getInstance('null-wrapper'), null);
 
+    t.end();
+});
+
+
+t.test('singleton/caches-instance', async (t) => {
+    // the wrapper must run once; later calls return the cached instance
+    let calls = 0;
+    singleton('counter-wrapper', async () => {
+        calls += 1;
+        return { id: calls };
+    });
+
+    const first = await getInstance('counter-wrapper');
+    const second = await getInstance('counter-wrapper');
+
+    t.equal(calls, 1);
+    t.equal(first, second);
+
     t.end();
 });

package/__tests__/math_numbers.test.js

@@ -10,5 +10,7 @@ t.test('numbers/toInteger', (t) => {
     t.equal(toInteger('1'), 1);
     t.equal(toInteger(1), 1);
     t.equal(toInteger('abcde'), 0);
+    // parseInt throws on a Symbol; toInteger must swallow it and return 0
+    t.equal(toInteger(Symbol('x')), 0);
     t.end();
 });

package/package.json

@@ -1,28 +1,28 @@
 {
-  "name": "@wizhut_tech/wizjs",
-  "version": "0.1.4",
-  "main": "index.js",
-  "devDependencies": {
-    "tap": "21.1.0"
+  "author": "vassilios.karakoidas@wizhut.tech",
+  "bugs": {
+    "url": "https://github.com/wizhut/wizjs/issues"
   },
   "description": "Simple but useful hacks for everyday javascript programming",
-  "scripts": {
-    "test": "tap run"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wizhut/wizjs.git"
+  "devDependencies": {
+    "tap": "21.7.4"
   },
+  "homepage": "https://github.com/wizhut/wizjs#readme",
   "keywords": [
     "javascript",
     "programming",
     "library",
     "utilities"
   ],
-  "author": "vassilios.karakoidas@wizhut.tech",
   "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/wizhut/wizjs/issues"
+  "main": "index.js",
+  "name": "@wizhut_tech/wizjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wizhut/wizjs.git"
+  },
+  "scripts": {
+    "test": "tap run"
   },
-  "homepage": "https://github.com/wizhut/wizjs#readme"
+  "version": "0.1.5"
 }