Release/v0.1.0 alpha.1

.gitignore

@@ -6,6 +6,9 @@
 # Visual Studio Code
 .vscode/
 
+# Claude Code
+.claude/
+
 # Node.js and npm
 node_modules/
 

CLAUDE.md

@@ -3,17 +3,21 @@
 Guidance for Claude Code (and other AI assistants) when working in this repository.
 
 ## Canonical Instructions
+
 The detailed, authoritative conventions for this project live in [`.github/copilot-instructions.md`](./.github/copilot-instructions.md); read that file first.
 This document is a concise map; `.github/copilot-instructions.md` is the source of truth.
 
 ## 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.
 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, and string helpers.
+
+A growing ESM-first TypeScript utility package for reusable number, random, string, and discriminator type-guard helpers.
 
 ## Common Commands
+
 - `npm ci` — install dependencies from the lockfile.
 - `npm run lint:all` — run both the JavaScript and TypeScript ESLint configurations.
 - `npm run build` — bundle the package to `_dist/` with tsdown.
@@ -22,13 +26,27 @@ A growing ESM-first TypeScript utility package for reusable number, random, and
 - `npm run docs` — generate TypeDoc API documentation to `_doc/`.
 
 ## Generated Output Directories (not committed)
-`_dist/` (build), `_coverage/` (coverage), and `_doc/` (TypeDoc) are generated and gitignored.
+
+`_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
+
 - Keep shared content between `README.md` and `docs/index.md` consistent; expected differences
   (front matter, headings, footer/links) are documented in `.github/copilot-instructions.md`.
 - The portfolio skills page (`docs/portfolio-skills.md`) and its generation/review workflow are
   described in the "Portfolio Page Generation and Maintenance" section of
   `.github/copilot-instructions.md`.
 - Release documentation under `docs/releases/` is maintained manually.
+
+## 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)):
+
+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
+3. **Instruction file sync** — `CLAUDE.md` and `copilot-instructions.md` are consistent and current
+4. **`package.json` keywords** — reflect current utility domains and features
+5. **GitHub repository topics** — align with `package.json` keywords
+6. **Branch code review** — convention compliance (static class pattern, JSDoc completeness, copyright headers, README/docs sync, test coverage), code quality (correctness, API consistency, efficiency, backward compatibility, reuse/DRY, runtime safety), and consistency (cross-source consistency across code/comments/docs, implicit pattern detection with maintainer notification)
+7. **Release readiness** (for merges to `main`) — version bump, release docs, TypeDoc entry points, publish workflow

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024-2026 Brittni Watkins
+Copyright (c) 2022-2026 Brittni Watkins
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -7,6 +7,11 @@ A growing toolkit of reusable, domain-agnostic TypeScript and JavaScript utiliti
 - [Latest Release](https://blwatkins.github.io/typescript-utils/doc/index.html)
 - [Documentation by Version Number](https://blwatkins.github.io/typescript-utils/releases.html)
 
+## History and Origins
+
+Development for this project originally began in March 2022 when I started creating utility classes in JavaScript to use across my personal algorithmic generative art projects.
+Over the years, the utilities have been refined, expanded, updated, and organized into a series of cohesive libraries that can be used in a variety of projects.
+
 ## License
 
 The source code of this project is licensed under the [MIT License](https://opensource.org/license/mit).
@@ -71,9 +76,9 @@ The full text of the license is included with the project source code.
 
 A huge thank you to all the open source contributors who have made this project possible by creating and maintaining the libraries and tools used in this project, and to the open source community for fostering collaboration and innovation.
 
-A special thank you to all the educators, mentors, and content creators who have shared their knowledge and expertise in the fields of web development and computer science.
+A special thank you to all the educators, mentors, and content creators who have shared their knowledge and expertise in the fields of algorithmic art, web development, and computer science.
 Thank you for giving me the tools, resources, opportunities, support, and inspiration to learn and grow as a developer.
 
 ----
 
-Copyright © 2024-2026 Brittni Watkins.
+Copyright © 2022-2026 Brittni Watkins.

docs/_includes/footer.html

@@ -3,7 +3,7 @@
     <div class="wrapper">
         <div class="footer-col-wrapper">
             <div class="footer-col">
-                <p>Copyright &copy; 2024-2026 Brittni Watkins.</p>
+                <p>Copyright &copy; 2022-2026 Brittni Watkins.</p>
             </div>
             <div class="footer-col">
                 <p style="text-align: right">{{ site.description | escape }}</p>

docs/index.md

@@ -12,6 +12,11 @@ A growing toolkit of reusable, domain-agnostic TypeScript and JavaScript utiliti
 - [Latest Release](./doc/index.html)
 - [Documentation by Version Number](./releases.md)
 
+## History and Origins
+
+Development for this project originally began in March 2022 when I started creating utility classes in JavaScript to use across my personal algorithmic generative art projects.
+Over the years, the utilities have been refined, expanded, updated, and organized into a series of cohesive libraries that can be used in a variety of projects.
+
 ## License
 
 The source code of this project is licensed under the [MIT License](https://opensource.org/license/mit).
@@ -76,5 +81,5 @@ The full text of the license is included with the project source code.
 
 A huge thank you to all the open source contributors who have made this project possible by creating and maintaining the libraries and tools used in this project, and to the open source community for fostering collaboration and innovation.
 
-A special thank you to all the educators, mentors, and content creators who have shared their knowledge and expertise in the fields of web development and computer science.
+A special thank you to all the educators, mentors, and content creators who have shared their knowledge and expertise in the fields of algorithmic art, web development, and computer science.
 Thank you for giving me the tools, resources, opportunities, support, and inspiration to learn and grow as a developer.

docs/portfolio-skills.md

@@ -1,11 +1,12 @@
 ---
 title: "Demonstrated Portfolio Skills"
+layout: post
 author:
   - Brittni Watkins
+  - Claude Code
   - GitHub Copilot
-layout: post
 date: 2026-05-27
-modified_date: 2026-07-02
+modified_date: 2026-07-08
 toc: true
 ---
 
@@ -15,24 +16,25 @@ 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, 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, 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.
 
 ## At a Glance
 
 - **Project Type:** TypeScript utility library package
-- **Primary Language:** [TypeScript](https://www.typescriptlang.org/)
-- **Primary Runtime:** [Node.js](https://nodejs.org/en)
-- **Primary Framework/Library:** Minimal framework-free utility architecture
-- **Build Pipeline:** [tsdown](https://tsdown.dev/)
-- **Quality Controls:** [ESLint](https://eslint.org/) and [GitHub Actions](https://github.com/features/actions)
-- **Dependency Automation:** [Dependabot](https://docs.github.com/en/code-security/concepts/supply-chain-security/about-dependabot-version-updates)
-- **Security Analysis:** [CodeQL](https://codeql.github.com/) via GitHub Actions
-- **Documentation Pattern:** [TypeDoc](https://typedoc.org/) output plus manually maintained release docs in `docs/releases/...`
+- **Primary Language:** TypeScript
+- **Primary Runtime:** Node.js
+- **Build Pipeline:** tsdown
+- **Quality Controls:** ESLint
+- **Automation:** GitHub Actions
+- **Dependency Automation:** Dependabot
+- **Security Analysis:** CodeQL via GitHub Actions
+- **Documentation Pattern:** TypeDoc and Jekyll (GitHub Pages)
 
 ## 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), [TypeBox](https://sinclairzx81.github.io/typebox/)
+- **Runtime & Libraries:** [Node.js](https://nodejs.org/en)
+- **Libraries:** [TypeBox](https://sinclairzx81.github.io/typebox/)
 - **Testing:** [Vitest](https://vitest.dev/)
 - **Build / Bundling:** [tsdown](https://tsdown.dev/)
 - **Code Quality:** [ESLint](https://eslint.org/)
@@ -43,7 +45,7 @@ TypeScript Utilities (`@blwatkins/utils`) is a growing, domain-agnostic utility
 - **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/)
 - **Code Analysis / Security:** [CodeQL](https://codeql.github.com/)
-- **Dependency Automation:** [Dependabot](https://docs.github.com/en/code-security/concepts/supply-chain-security/about-dependabot-version-updates)
+- **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)
 - **Environment Configuration:** Node.js version pinning via `.node-version`, plus Ruby version pinning for the Jekyll/Bundler docs site via `docs/.ruby-version`
 - **Development Environments:** [WebStorm](https://www.jetbrains.com/webstorm/), [Visual Studio Code](https://code.visualstudio.com/)
@@ -53,6 +55,8 @@ TypeScript Utilities (`@blwatkins/utils`) is a growing, domain-agnostic utility
 
 - Implements reusable static utility classes for string and number type checks to improve consistency across consuming code.
 - Provides a static discriminator registry with TypeBox schema validation to enable runtime type narrowing and reusable type guard generation for discriminated union patterns.
+- Provides a static `Random` class for generating random numbers, booleans, and selecting random elements from arrays, with a configurable underlying random function to enable use with seeded generators or custom sources.
+- Provides typed weighted random selection via `WeightedElementUtility` and `WeightedList`, using discriminator-validated element objects and a cumulative-weight selection strategy, enabling non-uniform random sampling from explicit probability distributions.
 - Provides a deterministic seeded pseudorandom number generator (xoshiro128**) with synchronous (FNV-1a) and asynchronous (SHA-256 via Web Crypto API) seed-hashing strategies, enabling reproducible random sequences from string seeds.
 - Uses explicit package export and type declaration mappings to improve compatibility for ESM consumers and TypeScript tooling.
 - Applies strict TypeScript compiler settings and type-aware lint rules to improve early detection of implementation defects.
@@ -81,10 +85,17 @@ The public entry point re-exports domain modules, and each domain module re-expo
 **Evidence:**
 
 - [src/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/index.ts)
-- [src/discriminator/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/discriminator/index.ts)
-- [src/number/index.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/number/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.
+
+**Evidence:**
+
+- [src/random/random.ts](https://github.com/blwatkins/typescript-utils/blob/main/src/random/random.ts)
+- [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)
 
 ### Strict typing and lint enforcement model
 
@@ -98,12 +109,12 @@ 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, 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:**
 
 - [package.json scripts](https://github.com/blwatkins/typescript-utils/blob/main/package.json)
-- [test/string/string-utility.test.ts](https://github.com/blwatkins/typescript-utils/blob/main/test/string/string-utility.test.ts)
+- [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)
 - [npm-test.yml](https://github.com/blwatkins/typescript-utils/blob/main/.github/workflows/npm-test.yml)
@@ -118,8 +129,6 @@ API docs are generated with TypeDoc, while the documentation site is built from
 - [gh-pages-jekyll.yml](https://github.com/blwatkins/typescript-utils/blob/main/.github/workflows/gh-pages-jekyll.yml)
 - [docs/index.md](https://github.com/blwatkins/typescript-utils/blob/main/docs/index.md)
 - [docs/releases directory](https://github.com/blwatkins/typescript-utils/tree/main/docs/releases)
-- [copilot-instructions.md](https://github.com/blwatkins/typescript-utils/blob/main/.github/copilot-instructions.md)
-- [CLAUDE.md](https://github.com/blwatkins/typescript-utils/blob/main/CLAUDE.md)
 
 ### Security scanning and dependency update automation
 

docs/releases.md

@@ -1,15 +1,24 @@
 ---
+title: "Releases"
 layout: post
 author:
   - Brittni Watkins
 date: 2026-05-18
-modified_date: 2026-07-02
-title: "Releases"
+modified_date: 2026-07-08
 tags:
   - releases
 toc: true
 ---
 
 ## v0.x
 
-- [v0.1.0-alpha.0](releases/v0.x/v0.1.x/v0.1.0-alpha.x/v0.1.0-alpha.0/doc/index.html) *(July 2, 2026)* - **@latest** **@alpha**
+### v0.1.x
+
+#### v0.1.0
+
+- v0.1.0 - *Coming soon*
+
+##### v0.1.0-alpha.x
+
+- [v0.1.0-alpha.0](releases/v0.x/v0.1.x/v0.1.0-alpha.x/v0.1.0-alpha.0/doc/index.html) *(July 2, 2026)* - **@latest**
+- [v0.1.0-alpha.1](releases/v0.x/v0.1.x/v0.1.0-alpha.x/v0.1.0-alpha.1/doc/index.html) *(July 8, 2026)* - **@alpha**