From 9797142ee12d9f7254f33d862a0f043b6162c24f Mon Sep 17 00:00:00 2001 From: blwatkins Date: Thu, 9 Jul 2026 21:39:52 -0500 Subject: [PATCH 01/12] Update fontawesome stylesheet to v7.3.0 --- docs/_includes/custom-head.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_includes/custom-head.html b/docs/_includes/custom-head.html index f520c75..ec7965a 100644 --- a/docs/_includes/custom-head.html +++ b/docs/_includes/custom-head.html @@ -1,4 +1,4 @@ + href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@7.3.0/css/all.min.css" + integrity="sha384-sTlsophtwz/I4myskS3OIJf5VvEojkXKZyBTWZm0YD/K1pN7C5wpBPLyrsbr1SU2" crossorigin="anonymous"> From e64ae38bde41e14cd5d69c9ddf06045451f3cdee Mon Sep 17 00:00:00 2001 From: blwatkins Date: Thu, 9 Jul 2026 21:48:39 -0500 Subject: [PATCH 02/12] Update portfolio-skills.md --- docs/portfolio-skills.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/portfolio-skills.md b/docs/portfolio-skills.md index 4fb9603..3092369 100644 --- a/docs/portfolio-skills.md +++ b/docs/portfolio-skills.md @@ -33,7 +33,7 @@ TypeScript Utilities (`@blwatkins/utils`) is a growing, domain-agnostic utility ## Skills and Tooling Inventory - **Languages:** [TypeScript](https://www.typescriptlang.org/), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), [Markdown](https://www.markdownguide.org/), [YAML](https://yaml.org/) -- **Runtime & Libraries:** [Node.js](https://nodejs.org/en) +- **Runtime:** [Node.js](https://nodejs.org/en) - **Libraries:** [TypeBox](https://sinclairzx81.github.io/typebox/) - **Testing:** [Vitest](https://vitest.dev/) - **Build / Bundling:** [tsdown](https://tsdown.dev/) From 1ca5369b40b802cf0569bd6f8ced13c1a9ba7dd5 Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 12:49:49 -0500 Subject: [PATCH 03/12] Update CLAUDE.md --- CLAUDE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4fa8282..f8ef490 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,12 +9,13 @@ This document is a concise map; `.github/copilot-instructions.md` is the source ## Keep These Two Files in Sync -This repository maintains both `CLAUDE.md` and `.github/copilot-instructions.md`. When you update guidance in one file that also applies to the other, mirror the change so the two stay consistent. +This repository maintains both `CLAUDE.md` and `.github/copilot-instructions.md`. +When you update guidance in one file that also applies to the other, mirror the change so the two stay consistent. Updates to `CLAUDE.md` should be reflected, when appropriate, in `.github/copilot-instructions.md`, and vice versa. ## Project Summary -A growing ESM-first TypeScript utility package for reusable number, random, string, and discriminator type-guard helpers. +A growing toolkit of reusable TypeScript and JavaScript utilities for numbers, strings, random number generation, and discriminator type-guard helpers, published to npm. ## Common Commands @@ -28,7 +29,6 @@ A growing ESM-first TypeScript utility package for reusable number, random, stri ## Generated Output Directories (not committed) `_dist/` (build), `_compiled/` (TypeScript `outDir`), `_coverage/` (coverage), and `_doc/` (TypeDoc) are generated and gitignored. -Note that the `docs/` Jekyll site separately includes committed sample documentation. ## Documentation Notes @@ -41,7 +41,7 @@ Note that the `docs/` Jekyll site separately includes committed sample documenta ## Pre-Merge and Release Review -Before merging a branch, complete these review steps (full details in the "Pre-Merge and Release Review" section of [`.github/copilot-instructions.md`](./.github/copilot-instructions.md)): +Before merging a branch, complete these review steps (full details in the ["Pre-Merge and Release Review" section of `.github/copilot-instructions.md`](./.github/copilot-instructions.md#pre-merge-and-release-review)): 1. **Validation** — `npm ci`, `npm run lint:all`, `npm run build`, `npm test` all pass 2. **Portfolio skills page** — review `docs/portfolio-skills.md` for accuracy; update `modified_date` if content changes From 531fa9a9d703390f26e9395ff4a1f12516c82da2 Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 14:03:56 -0500 Subject: [PATCH 04/12] Update copilot-instructions.md --- .github/copilot-instructions.md | 98 ++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 33 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f3473da..f9ccfa6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,9 +2,7 @@ ## Project Overview -This repository contains `@blwatkins/utils`, a growing ESM-first TypeScript utility package for reusable number, random, string, and discriminator type-guard helpers. - -The package source is maintained in `src/`, bundled to `_dist/` with `tsdown`, and documented through TypeDoc output plus manually maintained GitHub Pages release docs under `docs/`. +This repository contains `@blwatkins/utils`, a growing toolkit of reusable TypeScript and JavaScript utilities for numbers, strings, random number generation, and discriminator type-guard helpers ## Companion Instruction Files @@ -14,13 +12,15 @@ The two documents serve overlapping audiences and should stay consistent: when y ## Tech Stack -- TypeScript source compiled and bundled for ESM distribution -- Node.js runtime support aligned with `package.json` engines (`^22.22.0 || >=24`) -- `tsdown` for package builds and declaration output -- `Vitest` for unit testing -- `ESLint` for JavaScript and TypeScript linting -- `TypeDoc` for API documentation generation -- Jekyll-based `docs/` site content for published project and release documentation +- **Language:** TypeScript (targeting ES2022) +- **Runtime:** Node.js (^22.22.0 || >=24) +- **Package manager:** npm +- **Build:** tsdown (ESM output to `_dist/`) +- **Test:** Vitest (coverage via V8, output to `_coverage/`) +- **Documentation:** TypeDoc (output to `_doc/`) +- **Dependencies:** `typebox` (runtime/production dependency) +- **Site Generation:** Jekyll +- **Hosting & Deployment:** GitHub Pages and npm package registry ## Development and Validation @@ -37,7 +37,11 @@ The package is currently in an alpha release line and exports grouped utility mo - Install dependencies with `npm ci`. - Run lint checks with `npm run lint:all`. - Build with `npm run build`. -- Run tests with `npm run test`. +- Run tests with `npm test`. + +### Link Verification During Review + +As part of pull request review, verify that repository and package links (for example in `README.md`, `package.json`, or other project metadata) match the current repository and package coordinates. ## Pre-Merge and Release Review @@ -45,12 +49,7 @@ Complete the following steps before merging a branch to a release branch or to ` ### 1. Validation -Run the full validation suite and confirm everything passes cleanly: - -- `npm ci` — install dependencies from the lockfile -- `npm run lint:all` — both ESLint configurations report no errors -- `npm run build` — build completes with no errors -- `npm test` — all Vitest tests pass +Run the full [Validation Steps](#validation-steps) and confirm everything passes cleanly: ### 2. Portfolio Skills Page (`docs/portfolio-skills.md`) @@ -60,7 +59,7 @@ Review `docs/portfolio-skills.md` against the current repository state. If anyth - Bump `modified_date` to today; do not change the original `date` - Evidence links must always point to the `main` branch -Refer to the "Portfolio Page Generation and Maintenance" section for the full review checklist. +Refer to the ["Portfolio Page Generation and Maintenance" section](#portfolio-page-generation-and-maintenance) for the full review checklist. ### 3. Instruction File Sync @@ -80,7 +79,10 @@ Review the `keywords` array in `package.json`: ### 5. GitHub Repository Topics -Verify that the topics on the GitHub repository ([blwatkins/typescript-utils](https://github.com/blwatkins/typescript-utils)) reflect the current capabilities. Topics should align with `package.json` keywords where appropriate. Request the current topics to be updated, if necessary. Provide any topic change suggestions to the project maintainers and any accepted changes will be updated manually. +Verify that the topics on the GitHub repository ([blwatkins/typescript-utils](https://github.com/blwatkins/typescript-utils)) reflect the current capabilities. +Topics should align with `package.json` keywords where appropriate. +Request the current topics to be updated, if necessary. +Provide any topic change suggestions to the project maintainers and any accepted changes will be updated manually. ### 6. Branch Changes Code Review @@ -144,7 +146,6 @@ When preparing a release merge to `main`: - GitHub Actions runs CodeQL analysis for `actions`, `javascript-typescript`, and `ruby`. - Dependabot is configured for monthly updates to npm dependencies, GitHub Actions workflows, and Bundler dependencies under `docs/`. - The npm publish workflow uses npm Trusted Publishing with GitHub OIDC (`id-token: write`) instead of a committed registry token. -- The package declares `typebox` as a runtime dependency in `package.json`; all other toolchain packages are maintained through `devDependencies`. ## Development Guidelines @@ -155,14 +156,19 @@ Keep changes scoped to existing files unless a task explicitly requires scaffold - The package is ESM-only (`"type": "module"`), so keep imports/exports compatible with Node.js ESM resolution. - Public exports flow through module index files. For example, `src/index.ts` re-exports from `src/number/index.ts`, which re-exports from individual utility files. This pattern is intentional to maintain clear module boundaries and organization in both source code and generated documentation. - API documentation entry points stay module-scoped rather than pointing TypeDoc at the root package entry point. +- The project uses strict TypeScript settings (`strict`, `noImplicitAny`, `noUnusedLocals`, etc.) targeting ES2022 with `moduleResolution: bundler`. #### tsdown Build Output -This project uses `tsdown` to bundle and emit declaration files. When the output format is `esm`, tsdown emits format-specific file extensions: `.mjs` for the bundle and `.d.mts` for the declaration file, regardless of whether the source files use the `.ts` or `.mts` extension. The `types`, `module`, `main`, and `exports` fields in `package.json` should always reference these `.mjs`/`.d.mts` paths (e.g., `./_dist/index.mjs` and `./_dist/index.d.mts`). +This project uses `tsdown` to bundle and emit declaration files. +When the output format is `esm`, tsdown emits format-specific file extensions: `.mjs` for the bundle and `.d.mts` for the declaration file, regardless of whether the source files use the `.ts` or `.mts` extension. +The `types`, `module`, `main`, and `exports` fields in `package.json` should always reference these `.mjs`/`.d.mts` paths (e.g., `./_dist/index.mjs` and `./_dist/index.d.mts`). #### JavaScript Consumer Safety -This package is published as ESM and targets both TypeScript and JavaScript consumers. Retain runtime type guards and input validation even when TypeScript's type system would catch the same issue at compile time. JavaScript callers have no compile-time safety, so runtime checks are necessary for correctness. +This package is published as ESM and targets both TypeScript and JavaScript consumers. +Retain runtime type guards and input validation even when TypeScript's type system would catch the same issue at compile time. +JavaScript callers have no compile-time safety, so runtime checks are necessary for correctness. #### Static Classes @@ -218,6 +224,7 @@ Place annotations in the following order for consistency and readability: 1. `@throws` 1. `@default` 1. `@example` +1. `@type` 1. `@readonly` 1. `@private` 1. `@protected` @@ -228,7 +235,7 @@ Place annotations in the following order for consistency and readability: 1. `@since` 1. `@category` -Include other relevant tags (such as `@template`, `@type`) after the above, as appropriate for the context. +Include other relevant tags after the above, as appropriate for the context. ### File Headers @@ -260,17 +267,40 @@ All source files must include the MIT License copyright header at the top. ## Directory Structure -- `src/` - package source code -- `test/` - Vitest test suites -- `test/utils` - Shared test fixtures and scenario helpers for use across test suites -- `docs/` - GitHub Pages site content and manually maintained release documentation -- `_dist/` - build output generated by `npm run build` -- `_doc/` - TypeDoc output generated by `npm run docs` -- `.github/workflows/` - CI, publishing, documentation, and analysis workflows +``` +src/ + discriminator/ # Discriminated type-guard utilities and registry + number/ # Number utilities + random/ # Random number generation utilities + seeded-random/ # Seeded random number generator utilities + weighted-element/ # Weighted element selection utilities + string/ # String utilities + index.ts # Package entry point (re-exports all modules) +test/ # Vitest test suites (mirrors src/ module structure) + discriminator/ # Tests for the discriminator module + number/ # Tests for the number module + random/ # Tests for the random module + seeded-random/ # Tests for the seeded-random module + weighted-element/ # Tests for the weighted-element module + string/ # Tests for the string module + utils/ # Shared test fixtures and scenario helpers for use across test suites + input/ # Shared test input fixtures + test-case/ # Shared test-case helpers + scenarios/ # Reusable test-case scenario definitions +docs/ # GitHub Pages site content and manually maintained release documentation +.github/ + workflows/ # CI, publishing, documentation, and analysis workflows +_dist/ # Build output - generated by tsdown (not committed) +_compiled/ # TypeScript outDir output - generated by tsc (not committed) +_coverage/ # Coverage output - generated by Vitest (not committed) +_doc/ # Documentation output - generated by TypeDoc (not committed) +``` ## Documentation and GitHub Pages -- `README.md` and `docs/index.md` should stay in sync for shared content, but they are not expected to be identical. Expected differences include Jekyll front matter, file-specific introductory or heading sections, footer or copyright text, and internal link differences. Any addition, removal, or update to shared sections must be applied consistently to both files. +`README.md` and `docs/index.md` should stay in sync for shared content, but they are not expected to be identical. +Expected differences include Jekyll front matter, file-specific introductory or heading sections, footer or copyright text, and internal link differences. +Any addition, removal, or update to shared sections must be applied consistently to both files. ### TypeDoc Configuration @@ -284,7 +314,9 @@ All source files must include the MIT License copyright header at the top. ### Jekyll Build -- The Jekyll build uses the `jekyll-relative-links` plugin (configured in `docs/_config.yml`), which automatically converts relative `.md` links in `docs/` markdown files to their rendered `.html` paths. For example, `./portfolio-skills.md` in `docs/index.md` resolves to `portfolio-skills.html` on the published site. Use `.md` relative links within `docs/` source files; the build process will convert them correctly. +The Jekyll build uses the `jekyll-relative-links` plugin (configured in `docs/_config.yml`), which automatically converts relative `.md` links in `docs/` markdown files to their rendered `.html` paths. +For example, `./portfolio-skills.md` in `docs/index.md` resolves to `portfolio-skills.html` on the published site. +Use `.md` relative links within `docs/` source files; the build process will convert them correctly. ## Portfolio Page Generation and Maintenance @@ -386,7 +418,7 @@ Generate a Markdown file with these sections in order: - If claiming "output to directory X", link config/build files, not just example files - If claiming "TypeScript configuration", link `tsconfig.*`, ESLint config, or build config files, not just `.ts` source files - If describing current project behavior, prefer evidence that reflects the current runtime/configured implementation path, not only an illustrative or older example - - If a claim spans multiple concerns, link all relevant files needed to support it + - If a claim spans multiple concerns, link relevant files needed to support it - Focus on implementation facts and engineering intent, not promotional phrasing 8. **Current Gaps / Future Improvements** (bulleted list) From 455bbf612c3733fd152bf53d5f3e4d513aa8e6bb Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 14:04:35 -0500 Subject: [PATCH 05/12] Update npm-test.yml --- .github/workflows/npm-test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/npm-test.yml b/.github/workflows/npm-test.yml index 85dc178..67efe04 100644 --- a/.github/workflows/npm-test.yml +++ b/.github/workflows/npm-test.yml @@ -33,4 +33,4 @@ jobs: - run: npm ci - run: npm run lint:all - run: npm run build - - run: npm run test + - run: npm test From 3a85e4be9063a37dee96d96865ed05b7fc82c48a Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 14:19:45 -0500 Subject: [PATCH 06/12] Update copilot-instructions.md and CLAUDE.md --- .github/copilot-instructions.md | 2 +- CLAUDE.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f9ccfa6..a5a8ff0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ ## Project Overview -This repository contains `@blwatkins/utils`, a growing toolkit of reusable TypeScript and JavaScript utilities for numbers, strings, random number generation, and discriminator type-guard helpers +This repository contains `@blwatkins/utils`, a growing toolkit of reusable TypeScript and JavaScript utilities for number checks, string checks, random number and element selection (including weighted selection), deterministic seeded pseudorandom number generation, and a discriminator-based type guard registry. ## Companion Instruction Files diff --git a/CLAUDE.md b/CLAUDE.md index f8ef490..6ce5c34 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ Updates to `CLAUDE.md` should be reflected, when appropriate, in `.github/copilo ## Project Summary -A growing toolkit of reusable TypeScript and JavaScript utilities for numbers, strings, random number generation, and discriminator type-guard helpers, published to npm. +A growing toolkit of reusable TypeScript and JavaScript utilities for number checks, string checks, random number and element selection (including weighted selection), deterministic seeded pseudorandom number generation, and a discriminator-based type guard registry, published to npm. ## Common Commands From 1b2e837f510360f9c1b3ea70fd294eb7cea8c310 Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 14:19:51 -0500 Subject: [PATCH 07/12] Update portfolio-skills.md --- docs/portfolio-skills.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/portfolio-skills.md b/docs/portfolio-skills.md index 3092369..e2f378f 100644 --- a/docs/portfolio-skills.md +++ b/docs/portfolio-skills.md @@ -16,7 +16,8 @@ This page is a technical record of the skills, tools, and engineering practices ## Project Overview -TypeScript Utilities (`@blwatkins/utils`) is a growing, domain-agnostic utility package that provides reusable helpers for number checks, string checks, random number and element selection (including weighted selection), deterministic seeded pseudorandom number generation, and a discriminator-based type guard registry. The repository is maintained at [blwatkins/typescript-utils](https://github.com/blwatkins/typescript-utils), and it is built with TypeScript and tsdown. +TypeScript Utilities (`@blwatkins/utils`) is a growing toolkit of reusable TypeScript and JavaScript utilities for number checks, string checks, random number and element selection (including weighted selection), deterministic seeded pseudorandom number generation, and a discriminator-based type guard registry. +The repository is maintained at [blwatkins/typescript-utils](https://github.com/blwatkins/typescript-utils), and it is built with TypeScript and tsdown. ## At a Glance @@ -71,7 +72,8 @@ Each technical claim below is backed by a source link to the corresponding imple ### ESM package contract and artifact layout -The package is configured as ESM and publishes built artifacts from `_dist`, including declaration files and a scoped export map. The build pipeline generates those outputs from `src/index.ts` using tsdown. +The package is configured as ESM and publishes built artifacts from `_dist`, including declaration files and a scoped export map. +The build pipeline generates those outputs from `src/index.ts` using tsdown. **Evidence:** @@ -80,16 +82,19 @@ The package is configured as ESM and publishes built artifacts from `_dist`, inc ### Utility module composition and re-export boundaries -The public entry point re-exports domain modules, and each domain module re-exports dedicated types and classes. This keeps the package API small while still allowing clear internal organization by domain. +The public entry point re-exports domain modules, and each domain module re-exports dedicated types and classes. +This keeps the package API small while still allowing clear internal organization by domain. **Evidence:** - [src/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/index.ts) - [src/random/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/index.ts) +- [src/random/seeded-random/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/seeded-random/index.ts) ### Random number generation and weighted element selection -The `Random` class centralizes random number, boolean, and array-element selection behind a swappable random number source (defaulting to `Math.random`), enabling deterministic testing and drop-in use of the package's own seeded pseudorandom number generator. `WeightedElementUtility` builds on the discriminator registry to validate `WeightedElement` and `WeightedList` objects at runtime and performs non-uniform random selection using a cumulative-weight strategy. +The `Random` class centralizes random number, boolean, and array-element selection behind a swappable random number source (defaulting to `Math.random`), enabling deterministic testing and drop-in use of the package's own seeded pseudorandom number generator. +`WeightedElementUtility` builds on the discriminator registry to validate `WeightedElement` and `WeightedList` objects at runtime and performs non-uniform random selection using a cumulative-weight strategy. **Evidence:** @@ -99,7 +104,8 @@ The `Random` class centralizes random number, boolean, and array-element selecti ### Strict typing and lint enforcement model -TypeScript is configured with strict checks, including implicit-type and unused-code protections, to enforce predictable typing behavior. JavaScript and TypeScript lint configurations apply recommended and stricter rule sets for syntax safety and style consistency. +TypeScript is configured with strict checks, including implicit-type and unused-code protections, to enforce predictable typing behavior. +JavaScript and TypeScript lint configurations apply recommended and stricter rule sets for syntax safety and style consistency. **Evidence:** @@ -109,7 +115,9 @@ TypeScript is configured with strict checks, including implicit-type and unused- ### Test strategy and CI verification gates -The project uses Vitest for repeatable unit testing, including compile-time type checking of test files, with scripts wired into local and CI workflows. The primary CI workflow runs `npm ci`, lint, build, and tests across supported Node.js release lines before changes are accepted. Shared test input fixtures and scenario builders in `test/utils` support scenario-driven test suites and validation across modules. +The project uses Vitest for repeatable unit testing, including compile-time type checking of test files, with scripts wired into local and CI workflows. +The primary CI workflow runs `npm ci`, lint, build, and tests across supported Node.js release lines before changes are accepted. +Shared test input fixtures and scenario builders in `test/utils` support scenario-driven test suites and validation across modules. **Evidence:** @@ -121,7 +129,8 @@ The project uses Vitest for repeatable unit testing, including compile-time type ### Documentation generation and GitHub Pages publishing path -API docs are generated with TypeDoc, while the documentation site is built from `docs/` using a Jekyll workflow and deployed to GitHub Pages. Release-specific docs are stored under a versioned directory structure in `docs/releases/...`. +API docs are generated with TypeDoc, while the documentation site is built from `docs/` using a Jekyll workflow and deployed to GitHub Pages. +Release-specific docs are stored under a versioned directory structure in `docs/releases/...`. **Evidence:** @@ -132,7 +141,8 @@ API docs are generated with TypeDoc, while the documentation site is built from ### Security scanning and dependency update automation -Security analysis is automated with a dedicated CodeQL workflow covering Actions and repository code languages. Dependency updates are automated with Dependabot for npm, GitHub Actions, and Bundler ecosystems, and package publishing uses trusted publishing permissions. +Security analysis is automated with a dedicated CodeQL workflow covering Actions and repository code languages. +Dependency updates are automated with Dependabot for npm, GitHub Actions, and Bundler ecosystems, and package publishing uses trusted publishing permissions. **Evidence:** From 06324049e487f4e0a21700b6e8b4c8eae44cbd8e Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 14:22:05 -0500 Subject: [PATCH 08/12] Update README.md and index.md --- README.md | 2 +- docs/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9c0ae98..a01fc73 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # TypeScript Utilities -A growing toolkit of reusable, domain-agnostic TypeScript and JavaScript utilities for everyday development. +A growing toolkit of reusable TypeScript and JavaScript utilities for number checks, string checks, random number and element selection (including weighted selection), deterministic seeded pseudorandom number generation, and a discriminator-based type guard registry. ## Documentation diff --git a/docs/index.md b/docs/index.md index 864a4d4..85ea653 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ layout: page ## About This Project -A growing toolkit of reusable, domain-agnostic TypeScript and JavaScript utilities for everyday development. +A growing toolkit of reusable TypeScript and JavaScript utilities for number checks, string checks, random number and element selection (including weighted selection), deterministic seeded pseudorandom number generation, and a discriminator-based type guard registry. ## Documentation From d087ead1dd82909e790c4132b0bbff9290489df8 Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 14:37:28 -0500 Subject: [PATCH 09/12] Update portfolio-skills.md --- docs/portfolio-skills.md | 49 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/docs/portfolio-skills.md b/docs/portfolio-skills.md index e2f378f..29a4be1 100644 --- a/docs/portfolio-skills.md +++ b/docs/portfolio-skills.md @@ -6,7 +6,7 @@ author: - Claude Code - GitHub Copilot date: 2026-05-27 -modified_date: 2026-07-08 +modified_date: 2026-07-10 toc: true --- @@ -91,6 +91,28 @@ This keeps the package API small while still allowing clear internal organizatio - [src/random/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/index.ts) - [src/random/seeded-random/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/seeded-random/index.ts) +### String and number type-guard utilities + +`StringUtility` and `NumberUtility` provide static runtime type guards, such as non-empty and single-line trimmed string checks and positive-integer checks, so consuming code gets both TypeScript narrowing and JavaScript-safe runtime validation from a single call. +`ColorStringUtility` builds on `StringUtility` to validate hex color string formats (`#RRGGBB` and `#RRGGBBAA`). + +**Evidence:** + +- [src/string/string-utility.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/string/string-utility.ts) +- [src/number/number-utility.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/number/number-utility.ts) +- [src/string/color-string-utility.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/string/color-string-utility.ts) + +### Discriminator-based type guard registry + +`DiscriminatorRegistry` maintains a static map of unique discriminator values to validator functions, returning a reusable `TypeGuard` for each registration and enforcing discriminator shape and uniqueness at registration time. +The `Discriminated` type and its TypeBox schema define the minimal shape required for a registry-validated object, and `Discriminators` centralizes the discriminator string constants used across the package, such as the one backing `WeightedElement`. + +**Evidence:** + +- [src/discriminator/discriminator-registry.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/discriminator/discriminator-registry.ts) +- [src/discriminator/discriminated.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/discriminator/discriminated.ts) +- [src/discriminator/discriminators.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/discriminator/discriminators.ts) + ### Random number generation and weighted element selection The `Random` class centralizes random number, boolean, and array-element selection behind a swappable random number source (defaulting to `Math.random`), enabling deterministic testing and drop-in use of the package's own seeded pseudorandom number generator. @@ -102,6 +124,16 @@ The `Random` class centralizes random number, boolean, and array-element selecti - [src/random/weighted-element/weighted-element.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/weighted-element/weighted-element.ts) - [src/random/weighted-element/weighted-element-utility.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/weighted-element/weighted-element-utility.ts) +### Deterministic seeded pseudorandom number generation + +`SeededRandomNumberGenerator` implements the xoshiro128** algorithm over a validated 128-bit state to produce a reproducible, uniformly distributed sequence of floats. +`RandomNumberGeneratorFactory` derives that initial state from a string seed (with an optional namespace and version) using either a synchronous FNV-1a hash or an asynchronous SHA-256 hash via the Web Crypto API, giving callers reproducible sequences without managing raw generator state themselves. + +**Evidence:** + +- [src/random/seeded-random/seeded-random-number-generator.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/seeded-random/seeded-random-number-generator.ts) +- [src/random/seeded-random/random-number-generator-factory.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/seeded-random/random-number-generator-factory.ts) + ### Strict typing and lint enforcement model TypeScript is configured with strict checks, including implicit-type and unused-code protections, to enforce predictable typing behavior. @@ -113,18 +145,25 @@ JavaScript and TypeScript lint configurations apply recommended and stricter rul - [eslint.config.js.mjs](https://github.com/blwatkins/typescript-utils/blob/main/eslint.config.js.mjs) - [eslint.config.ts.mjs](https://github.com/blwatkins/typescript-utils/blob/main/eslint.config.ts.mjs) -### Test strategy and CI verification gates +### Test strategy and scenario-driven fixtures -The project uses Vitest for repeatable unit testing, including compile-time type checking of test files, with scripts wired into local and CI workflows. -The primary CI workflow runs `npm ci`, lint, build, and tests across supported Node.js release lines before changes are accepted. +The project uses Vitest for repeatable unit testing, including compile-time type checking of test files. Shared test input fixtures and scenario builders in `test/utils` support scenario-driven test suites and validation across modules. **Evidence:** -- [package.json scripts](https://github.com/blwatkins/typescript-utils/blob/main/package.json) - [vitest.config.ts](https://github.com/blwatkins/typescript-utils/blob/main/vitest.config.ts) - [test/utils/input/string-inputs.ts](https://github.com/blwatkins/typescript-utils/blob/main/test/utils/input/string-inputs.ts) - [test/utils/test-case/scenarios/random-number-generator-factory-scenarios.ts](https://github.com/blwatkins/typescript-utils/blob/main/test/utils/test-case/scenarios/random-number-generator-factory-scenarios.ts) + +### CI verification gates + +Lint, build, and test scripts are wired into local and CI workflows via `package.json`. +The primary CI workflow runs `npm ci`, lint, build, and tests across supported Node.js release lines before changes are accepted. + +**Evidence:** + +- [package.json scripts](https://github.com/blwatkins/typescript-utils/blob/main/package.json) - [npm-test.yml](https://github.com/blwatkins/typescript-utils/blob/main/.github/workflows/npm-test.yml) ### Documentation generation and GitHub Pages publishing path From d9272eaa884779d78b317cea99eb19fcc63dbcd3 Mon Sep 17 00:00:00 2001 From: Brittni Watkins Date: Fri, 10 Jul 2026 15:04:26 -0500 Subject: [PATCH 10/12] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/portfolio-skills.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/portfolio-skills.md b/docs/portfolio-skills.md index 29a4be1..10cb059 100644 --- a/docs/portfolio-skills.md +++ b/docs/portfolio-skills.md @@ -127,7 +127,7 @@ The `Random` class centralizes random number, boolean, and array-element selecti ### Deterministic seeded pseudorandom number generation `SeededRandomNumberGenerator` implements the xoshiro128** algorithm over a validated 128-bit state to produce a reproducible, uniformly distributed sequence of floats. -`RandomNumberGeneratorFactory` derives that initial state from a string seed (with an optional namespace and version) using either a synchronous FNV-1a hash or an asynchronous SHA-256 hash via the Web Crypto API, giving callers reproducible sequences without managing raw generator state themselves. +`RandomNumberGeneratorFactory` derives that initial state from a string seed and optional namespace, using either a synchronous FNV-1a hash (with an optional version selecting the hashing offsets) or an asynchronous SHA-256 hash via the Web Crypto API, giving callers reproducible sequences without managing raw generator state themselves. **Evidence:** From 726a092f079dba4dde2a1c4447b09070f6f4512a Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 15:08:34 -0500 Subject: [PATCH 11/12] Update portfolio-skills.md and copilot-instructions.md --- .github/copilot-instructions.md | 2 +- docs/portfolio-skills.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a5a8ff0..764fe4e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -20,7 +20,7 @@ The two documents serve overlapping audiences and should stay consistent: when y - **Documentation:** TypeDoc (output to `_doc/`) - **Dependencies:** `typebox` (runtime/production dependency) - **Site Generation:** Jekyll -- **Hosting & Deployment:** GitHub Pages and npm package registry +- **Hosting & Deployment:** GitHub Pages, npm package registry, and GitHub package registry ## Development and Validation diff --git a/docs/portfolio-skills.md b/docs/portfolio-skills.md index 10cb059..d85a2a2 100644 --- a/docs/portfolio-skills.md +++ b/docs/portfolio-skills.md @@ -44,7 +44,7 @@ The repository is maintained at [blwatkins/typescript-utils](https://github.com/ - **Dependency Management:** [npm](https://www.npmjs.com/) - **Versioning & Platform:** [Git](https://git-scm.com/), [GitHub](https://github.com/) - **Automation:** [GitHub Actions](https://github.com/features/actions) -- **Hosting & Deployment:** [GitHub Pages](https://docs.github.com/en/pages), [npm Package Registry](https://www.npmjs.com/) +- **Hosting & Deployment:** [GitHub Pages](https://docs.github.com/en/pages), [npm package registry](https://www.npmjs.com/), [GitHub package registry](https://docs.github.com/en/packages) - **Code Analysis / Security:** [CodeQL](https://codeql.github.com/) - **Dependency Automation:** [Dependabot](https://docs.github.com/en/code-security/concepts/supply-chain-security/dependabot-version-updates) - **Development Utilities:** [npm CLI](https://docs.npmjs.com/cli) From 7c7c53397f5b1679bfaddb4f6c49083f5a174b63 Mon Sep 17 00:00:00 2001 From: blwatkins Date: Fri, 10 Jul 2026 15:08:40 -0500 Subject: [PATCH 12/12] Update package.json --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index b74c333..84884b5 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,7 @@ "version": "0.1.0-alpha.1", "license": "MIT", "private": false, - "description": "A growing toolkit of reusable, domain-agnostic TypeScript and JavaScript utilities for everyday development.", + "description": "A growing toolkit of reusable TypeScript and JavaScript utilities for number checks, string checks, random number and element selection (including weighted selection), deterministic seeded pseudorandom number generation, and a discriminator-based type guard registry.", "author": { "name": "Brittni Watkins", "url": "https://blwatkins.github.io/"