raindrops-on-roses 0.0.3 → 0.0.5

package/README.md

@@ -17,16 +17,119 @@ And then I don't feel so bad_
 
 ## Install
 
+Install the complete library:
+
 ```sh
 npm install raindrops-on-roses
 ```
 
+Or install only the package you need:
+
+```sh
+npm install @aleclloydprobert/number-clamp
+```
+
+You can also install an aggregate package:
+
+```sh
+npm install @aleclloydprobert/number
+```
+
 ## Usage
 
+From the complete library:
+
 ```ts
 import { clamp } from "raindrops-on-roses";
 ```
 
+From an aggregate package:
+
+```ts
+import { clamp } from "@aleclloydprobert/number";
+```
+
+From the smallest individual package:
+
+```ts
+import { clamp } from "@aleclloydprobert/number-clamp";
+```
+
+## Package architecture
+
+`raindrops-on-roses` uses a module tree as its source of truth.
+
+Human-authored source lives in `modules/`. Publishable npm workspaces under `packages/` are generated from that tree.
+
+```text
+modules/
+└── number/
+    ├── clamp/
+    ├── nice-number/
+    └── numbers-from-seed/
+```
+
+This produces:
+
+```text
+@aleclloydprobert/number
+@aleclloydprobert/number-clamp
+@aleclloydprobert/number-nice-number
+@aleclloydprobert/number-numbers-from-seed
+raindrops-on-roses
+```
+
+Package names are derived from the module path:
+
+```text
+number
+→ @aleclloydprobert/number
+
+number/clamp
+→ @aleclloydprobert/number-clamp
+
+vector/poor
+→ @aleclloydprobert/vector-poor
+
+vector/poor/distance
+→ @aleclloydprobert/vector-poor-distance
+```
+
+Parent module paths automatically become aggregate packages.
+
+For example:
+
+```text
+modules/
+└── vector/
+    └── poor/
+        ├── distance/
+        └── mid-point/
+```
+
+generates:
+
+```text
+@aleclloydprobert/vector
+@aleclloydprobert/vector-poor
+@aleclloydprobert/vector-poor-distance
+@aleclloydprobert/vector-poor-mid-point
+```
+
+with a dependency graph like:
+
+```text
+@aleclloydprobert/vector
+        │
+        ▼
+@aleclloydprobert/vector-poor
+        │
+        ├── @aleclloydprobert/vector-poor-distance
+        └── @aleclloydprobert/vector-poor-mid-point
+```
+
+The `raindrops-on-roses` package is the root aggregate and depends only on top-level aggregate packages.
+
 ## Contribute
 
 `raindrops-on-roses` is an open-source library, and welcomes contributions from humans. If like us you love crafting beautiful and useful utilities, you can open a PR!
@@ -38,157 +141,297 @@ import { clamp } from "raindrops-on-roses";
 
 ### Adding a new function
 
-- Clone the repository and install dependencies:
-
-  ```sh
-  npm install
-  ```
+Clone the repository and install dependencies:
 
-- Use the generator to create a new function:
-
-  ```sh
-  npm run add:function -- <functionName>
-  ```
+```sh
+npm install
+```
 
-- The generator will prompt you to:
-  - choose whether the function is `pure` or `composed`
-  - choose an existing category, such as `numbers`, or create a new one
+Use the generator:
 
-- Each function is created as its own npm workspace package. The generator creates:
-  - `src/index.ts` for the implementation
-  - `test/index.test.ts` for tests
-  - `package.json` for the individual npm package
-  - `tsconfig.json`
-  - `vite.config.ts`
-  - the corresponding dependency and export in the `raindrops-on-roses` umbrella package
+```sh
+npm run add:function -- <functionName>
+```
 
-- New utility packages start at version `0.0.0`.
+The generator will prompt you to choose an existing module path or create a new one.
 
-- After generating a function, install again so npm registers the new workspace:
+For example, adding `distance` under `vector/poor` creates:
 
-  ```sh
-  npm install
-  ```
+```text
+modules/
+└── vector/
+    └── poor/
+        └── distance/
+            ├── src/
+            │   └── index.ts
+            ├── test/
+            │   └── index.test.ts
+            └── README.md
+```
 
-- The generated tests are intentionally incomplete and should initially fail.
+The generator creates only the human-authored module. It does not manually create npm manifests, Vite configs, TypeScript configs, aggregate exports, or umbrella dependencies.
 
-- Implement and document the function, then replace the placeholder test with meaningful test cases.
+After creating the module, the package assembler generates all required npm workspaces automatically.
 
-- Every function must:
-  - be fully typed
-  - have JSDoc documentation
-  - have 100% test coverage
+The generated test is intentionally incomplete and should initially fail.
 
-- Run the full test suite:
+Implement and document the function, then replace the placeholder test with meaningful test cases.
 
-  ```sh
-  npm run test
-  ```
+Every function must:
 
-- Check coverage:
+- be fully typed
+- have JSDoc documentation
+- have 100% test coverage
 
-  ```sh
-  npm run coverage
-  ```
+Run the test suite:
 
-- Verify that every package builds successfully:
+```sh
+npm run test
+```
 
-  ```sh
-  npm run build
-  ```
+Check coverage:
 
-You should not need to manually add the function to the umbrella `package.json`, `index.ts`, or Vite configuration. The generator handles this automatically.
+```sh
+npm run coverage
+```
 
-Do not attempt to publish packages created as part of a contribution. Publishing and versioning are handled by the maintainers as part of the release process.
+Build every package:
 
-### File system
+```sh
+npm run build
+```
 
-There are two types of functions:
+You should not manually edit generated files under `packages/`. Changes belong in `modules/` or in the repository's generation scripts.
 
-- **pure**: an independent unit with no side effects and no dependency on other `raindrops-on-roses` utilities
-- **composed**: a function built by composing existing utilities
+Do not attempt to publish packages created as part of a contribution. Publishing and versioning are handled by the maintainers.
 
-Every utility is also an independent npm workspace package.
+## File system
 
-For example, the `clamp` utility is stored as:
+The repository separates authored modules from generated npm packages.
 
 ```text
-packages/
-├── pure/
-│   └── numbers/
-│       └── clamp/
-│           ├── src/
-│           │   └── index.ts
-│           ├── test/
-│           │   └── index.test.ts
-│           ├── package.json
-│           ├── tsconfig.json
-│           └── vite.config.ts
+raindrops-on-roses/
+├── modules/                         # source of truth
+│   └── number/
+│       ├── clamp/
+│       │   ├── src/
+│       │   │   └── index.ts
+│       │   ├── test/
+│       │   │   └── index.test.ts
+│       │   └── README.md
+│       ├── nice-number/
+│       └── numbers-from-seed/
+│
+├── packages/                        # generated npm workspaces
+│   ├── number/
+│   ├── number-clamp/
+│   ├── number-nice-number/
+│   ├── number-numbers-from-seed/
+│   └── raindrops-on-roses/
 │
-└── raindrops-on-roses/
-    ├── src/
-    │   └── index.ts
-    ├── package.json
-    ├── tsconfig.json
-    └── vite.config.ts
+├── config/
+│   └── vite.library.ts
+│
+├── scripts/
+│   ├── assemble.mjs
+│   ├── bootstrap.mjs
+│   ├── build.mjs
+│   ├── droplet.mjs
+│   ├── publish.mjs
+│   └── release.mjs
+│
+├── packages.config.mjs
+├── packages.versions.json
+├── package.json
+└── tsconfig.base.json
 ```
 
-The directory hierarchy describes the kind of utility:
+### Authored modules
+
+Each leaf module contains only the things contributors maintain directly:
 
 ```text
-packages/<type>/<category>/<utility>/
+modules/<path>/<utility>/
+├── src/
+│   └── index.ts
+├── test/
+│   └── index.test.ts
+└── README.md
 ```
 
 For example:
 
 ```text
-packages/pure/numbers/clamp/
-packages/pure/numbers/numbers-from-seed/
+modules/number/clamp/
+modules/number/nice-number/
+modules/number/numbers-from-seed/
 ```
 
-The utility directory name uses kebab-case, while the exported JavaScript function keeps its normal camelCase name:
+The exported JavaScript function keeps its normal camelCase name while the directory uses kebab-case:
 
 ```text
 numbersFromSeed
 ↓
-packages/pure/numbers/numbers-from-seed/
+modules/number/numbers-from-seed/
 ↓
-@aleclloydprobert/numbers-from-seed
+@aleclloydprobert/number-numbers-from-seed
 ```
 
-Each utility package can be installed independently:
+### Generated packages
+
+Run:
 
 ```sh
-npm install @aleclloydprobert/clamp
+npm run assemble
 ```
 
-and imported directly:
+to regenerate npm workspaces from the module tree.
+
+Generated packages contain npm/build infrastructure such as:
+
+```text
+package.json
+tsconfig.json
+vite.config.ts
+src/index.ts
+README.md
+.raindrops-generated
+```
+
+Aggregate package sources are generated as re-exports of their direct child packages.
+
+For example:
 
 ```ts
-import { clamp } from "@aleclloydprobert/clamp";
+export * from "@aleclloydprobert/number-clamp";
+export * from "@aleclloydprobert/number-nice-number";
+export * from "@aleclloydprobert/number-numbers-from-seed";
 ```
 
-The same utility is also re-exported by the umbrella package:
+The umbrella package is generated from top-level aggregates, for example:
 
 ```ts
-import { clamp } from "raindrops-on-roses";
+export * from "@aleclloydprobert/number";
 ```
 
-The umbrella package depends on the individual utility packages and provides the complete library API while remaining tree-shakeable.
+### Build order
 
-When using:
+Packages are built in dependency order by:
 
 ```sh
-npm run add:function -- <functionName>
+npm run build
+```
+
+Leaf packages build first, then aggregates, then the umbrella package.
+
+For example:
+
+```text
+@aleclloydprobert/number-clamp
+        ↓
+@aleclloydprobert/number
+        ↓
+raindrops-on-roses
+```
+
+### Versions and releases
+
+Generated `package.json` files are not the source of truth for package versions.
+
+Versions are stored in:
+
+```text
+packages.versions.json
+```
+
+Prepare a release with:
+
+```sh
+npm run release
+```
+
+The release script lets maintainers select changed leaf modules and choose `patch`, `minor`, or `major`.
+
+Version changes propagate through dependent aggregates automatically.
+
+For example:
+
+```text
+number/clamp changes
+        ↓
+@aleclloydprobert/number-clamp
+        ↓
+@aleclloydprobert/number
+        ↓
+raindrops-on-roses
+```
+
+Unchanged branches keep their existing versions.
+
+### Publishing
+
+Publishing is dependency-aware and skips package versions that already exist on npm.
+
+The publish order is:
+
+```text
+leaf packages
+    ↓
+aggregate packages
+    ↓
+raindrops-on-roses
+```
+
+Normal releases are published through GitHub Actions with npm Trusted Publishing.
+
+When a brand-new module path introduces npm package names that have never existed before, maintainers can inspect the bootstrap plan with:
+
+```sh
+npm run bootstrap:dry
 ```
 
-you will be prompted to select:
+and then bootstrap the new package names with:
 
-1. `pure` or `composed`
-2. an existing category or a new category
+```sh
+npm run bootstrap
+```
+
+The bootstrap script publishes new package names once and configures Trusted Publishing for future CI releases.
+
+### Package levels
+
+Consumers can choose how much of the library they want to install.
+
+Individual utility:
+
+```sh
+npm install @aleclloydprobert/number-clamp
+```
 
-The generator then creates the complete workspace package in the appropriate location.
+```ts
+import { clamp } from "@aleclloydprobert/number-clamp";
+```
+
+Aggregate:
+
+```sh
+npm install @aleclloydprobert/number
+```
+
+```ts
+import { clamp, niceNumber, numbersFromSeed } from "@aleclloydprobert/number";
+```
+
+Complete library:
+
+```sh
+npm install raindrops-on-roses
+```
+
+```ts
+import { clamp, niceNumber, numbersFromSeed } from "raindrops-on-roses";
+```
 
-### Show your love
+## Show your love
 
 - In the JsDoc above your function, feel free to add a quote you like. It should ideally be related to the function.

package/dist/index.d.ts

@@ -1,4 +1,2 @@
-export { clamp } from "@aleclloydprobert/clamp";
-export { numbersFromSeed } from "@aleclloydprobert/numbers-from-seed";
-export { niceNumber } from "@aleclloydprobert/nice-number";
+export * from "@aleclloydprobert/number";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,4 +1 @@
-export { clamp } from "@aleclloydprobert/clamp";
-export { numbersFromSeed } from "@aleclloydprobert/numbers-from-seed";
-export { niceNumber } from "@aleclloydprobert/nice-number";
-//# sourceMappingURL=index.js.map
+export * from "@aleclloydprobert/number";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raindrops-on-roses",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "sideEffects": false,
   "files": [
@@ -12,14 +12,14 @@
       "import": "./dist/index.js"
     }
   },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.json"
+  },
   "dependencies": {
-    "@aleclloydprobert/clamp": "0.0.1",
-    "@aleclloydprobert/nice-number": "0.0.1",
-    "@aleclloydprobert/numbers-from-seed": "0.0.1"
+    "@aleclloydprobert/number": "0.0.1"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepack": "node ../../scripts/copy-readme.mjs"
+  "publishConfig": {
+    "access": "public"
   },
   "license": "MIT",
   "repository": {

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC"}