refactor: unmonorepo webapi package

Author: jderochervlk

.github/workflows/ci.yml

@@ -56,62 +56,32 @@ jobs:
         id: vars
         run: echo "COMMIT_HASH=$(git rev-parse --short HEAD)" >> $GITHUB_ENV
 
-      - name: Update workspace versions to -<commit-hash>
+      - name: Update package version to -<commit-hash>
         env:
           PACKAGE_VERSION: ${{ steps.package-version.outputs.current-version }}-experimental-${{ env.COMMIT_HASH }}
         run: |
           node <<'NODE'
           const fs = require("node:fs");
-          const path = require("node:path");
-
-          const packagesDir = path.join(process.cwd(), "packages");
-          const version = process.env.PACKAGE_VERSION;
-          const packages = fs
-            .readdirSync(packagesDir)
-            .filter((dir) => fs.existsSync(path.join(packagesDir, dir, "package.json")))
-            .map((dir) => {
-              const packageJsonPath = path.join(packagesDir, dir, "package.json");
-              const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-              return { packageJsonPath, packageJson };
-            });
-          const workspaceNames = new Set(packages.map(({ packageJson }) => packageJson.name));
-
-          for (const { packageJsonPath, packageJson } of packages) {
-            packageJson.version = version;
-
-            for (const field of ["dependencies", "peerDependencies", "devDependencies"]) {
-              if (!packageJson[field]) continue;
-
-              for (const dependencyName of Object.keys(packageJson[field])) {
-                if (workspaceNames.has(dependencyName)) {
-                  packageJson[field][dependencyName] = version;
-                }
-              }
-            }
-
-            fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
-          }
+          const packageJsonPath = "package.json";
+          const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+          packageJson.version = process.env.PACKAGE_VERSION;
+          fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
           NODE
 
-      - name: Package npm workspaces
-        run: npm pack --workspaces
+      - name: Package npm package
+        run: npm pack
 
       - name: Upload npm package artifact
         uses: actions/upload-artifact@v7
         with:
           name: npm-packages
           path: "*.tgz"
 
-      - name: Publish npm packages
+      - name: Publish npm package
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
-        run: |
-          for package in packages/*; do
-            if [ -f "$package/package.json" ]; then
-              npm publish --workspace "$package" --access public --tag experimental
-            fi
-          done
+        run: npm publish --access public --tag experimental
 
   deploy-docs:
     needs: build

.gitignore

@@ -5,6 +5,8 @@
 dist/
 tmp/
 docs/public/llm.txt
+.npm-cache/
+*.tgz
 *~
 .worktrees/
 
@@ -15,4 +17,6 @@ docs/public/llm.txt
 
 rescript.lock
 
+src/**/*.js
+tests/**/*.js
 **/*.res.js

README.md

@@ -17,10 +17,10 @@ and add `@rescript/webapi` to your `rescript.json`:
 ```json
 {
   "bs-dependencies": [
-+    "@rescript/webapi",
+    "@rescript/webapi"
   ],
   "bsc-flags": [
-+    "-open WebAPI.Global"
+    "-open WebApi.DOM.Global"
   ]
 }
 ```

docs/content/docs/contributing/api-modelling.mdx

@@ -88,8 +88,8 @@ mutable fillStyle: fillStyle
 When we wish to read and write the `fillStyle` property, we can use a helper module to lift the type to an actual ReScript variant:
 
 export const fillStyleModule = `
-open WebApiCanvas
-open WebApiDOM
+open WebApi.Canvas
+open WebApi.DOM
 
 external fromString: string => fillStyle = "%identity"
 external fromCanvasGradient: canvasGradient => fillStyle = "%identity"

docs/content/docs/contributing/getting-started.mdx

@@ -11,7 +11,7 @@ import { Aside } from "@astrojs/starlight/components";
   upside? It’s stupid easy to toss us a PR and make it better!
 </Aside>
 
-The [WebAPI](https://developer.mozilla.org/en-US/docs/Web/API) are vast and ever-growing. We need your help to make them better.  
+The [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) are vast and ever-growing. We need your help to make them better.  
 There is no way our [contributors](https://github.com/rescript-lang/experimental-rescript-webapi/graphs/contributors) can cover everything.  
 And that's where you come in! A small PR, focused on what you want to get out of this project can make a huge difference.
 

docs/content/docs/index.mdx

@@ -2,7 +2,7 @@
 title: Getting started
 description: Learn more about @rescript/webapi.
 hero:
-  title: "ReScript WebAPI"
+  title: "ReScript WebApi"
   tagline: ReScript bindings for everything you need in the browser.
   actions:
     - text: Let's go!
@@ -39,10 +39,10 @@ and add `@rescript/webapi` to your `rescript.json`:
 export const rescriptJson = `
 {
   "bs-dependencies": [
-    "@rescript/webapi",
+    "@rescript/webapi"
   ],
   "bsc-flags": [
-    "-open WebAPI.Global"
+    "-open WebApi.DOM.Global"
   ]
 }
 `;
@@ -54,14 +54,14 @@ export const rescriptJson = `
 After installing the package , you can use bindings for the various Web APIs as defined in [MDN](https://developer.mozilla.org/en-US/docs/Web/API).
 
 export const rescriptSample = `
-// Note that this only works when you added the \`-open WebAPI.Global\` bsc flag.
+// Note that this only works when you added the \`-open WebApi.DOM.Global\` bsc flag.
 let location = window.location
 
 // Access properties using \`.\`
 let href = location.href
 
 // Invoke methods using the \`->TypeModule.method\`
-location->Location.reload
+location->WebApi.DOM.Location.reload
 `;
 
 export const compiledSample = `

docs/content/docs/philosophy.mdx

@@ -16,13 +16,12 @@ The bindings are generated from the [MDN Web API documentation](https://develope
 
 In other words, if you are searching for a specific JavaScript binding, begin your journey at the [MDN Web API documentation](https://developer.mozilla.org/en-US/docs/Web/API) and determine which module contains your sample. Ensure that the module is available in the bindings by checking the specific API. Please [open an issue](https://github.com/rescript-lang/experimental-rescript-webapi/issues/new/choose) if you require an API that is not yet present.
 
-Each API will have its interface and auxiliary types in a module named after the API, suffixed with `API` to prevent collisions with the type module.
+Each feature is grouped under a `WebApi.<Feature>` module so related interfaces and helper modules stay together without relying on flat package-wide names.
 
 ```ReScript
-open WebAPI.Global
-open WebAPI.DOMAPI
+open WebApi.DOM.Global
 
-let myElement: element = document->Document.createElement( ~localName = "div")
+let myElement: WebApi.DOM.Types.element = document->WebApi.DOM.Document.createElement("div")
 ```
 
 ## Interfaces
@@ -44,18 +43,10 @@ JavaScript supports function overloads, where a function can have multiple signa
 In some cases, type conversion will be required. Subtypes can safely be cast to their base type using conversion helpers within their module.
 
 ```ReScript
-open WebAPI
+open WebApi.DOM.Global
 
-let element: element = document->Document.createElement( ~localName = "div")
-let node: node = element->Element.asNode
+let element: WebApi.DOM.Types.element = document->WebApi.DOM.Document.createElement("div")
+let node: WebApi.DOM.Types.node = element->WebApi.DOM.Element.asNode
 ```
 
-Any other conversions can be performed using the `Base.unsafeConversation` helper. This should be done with caution, as it can lead to runtime errors.
-
-```ReScript
-open WebAPI
-
-let element: element = document->Document.createElement( ~localName = "div")
-// This is potentially unsafe, as the type system cannot guarantee the conversion
-let divElement: htmlDivElement = element->Base.unsafeConversation
-```
+Any other conversions should be treated as unsafe casts and used with caution, because the type system cannot guarantee they are valid at runtime.

docs/llm.js

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs/promises";
+import { featureSpecs, publicNameForLeafModule } from "../scripts/unmonorepo/feature-spec.mjs";
 
 const execAsync = promisify(exec);
 
@@ -33,10 +34,7 @@ async function getDocJson(filePath) {
 async function processFile(filePath) {
   const json = await getDocJson(filePath);
   const relativePath = path.relative(path.join(import.meta.dirname, ".."), filePath);
-  const parts = relativePath.split(path.sep);
-  const packageName = parts[1];
-  const leafName = path.basename(filePath, ".res");
-  const moduleName = leafName === "Types" ? packageName : `${packageName}.${leafName}`;
+  const moduleName = moduleNameForFile(relativePath);
 
   const types = [];
   const functions = [];
@@ -97,7 +95,26 @@ Module: ${moduleName}${typeString}${functionString}
 `;
 }
 
-const pattern = "../packages/*/src/**/*.res";
+const specByDir = new Map(featureSpecs.map((spec) => [spec.dirName, spec]));
+
+function moduleNameForFile(relativePath) {
+  const [, dirName, fileName] = relativePath.split(path.sep);
+  const spec = specByDir.get(dirName);
+
+  if (!spec) {
+    throw new Error(`Unsupported source directory for documentation: ${relativePath}`);
+  }
+
+  const leafName = path.basename(fileName, ".res");
+
+  if (leafName === spec.publicModule) {
+    return `WebApi.${spec.publicModule}`;
+  }
+
+  return `WebApi.${spec.publicModule}.${publicNameForLeafModule(leafName, spec.internalPrefix)}`;
+}
+
+const pattern = "../src/*/**/*.res";
 const files = [];
 for await (const file of fs.glob(pattern, { recursive: true, cwd: import.meta.dirname })) {
   files.push(path.join(import.meta.dirname, file));
@@ -109,9 +126,9 @@ const packageJson = await fs.readFile(path.join(import.meta.dirname, "../package
 let version = JSON.parse(packageJson).version;
 const sha = await execAsync("git rev-parse --short HEAD").then(({ stdout }) => stdout.trim());
 const fullVersion = `${version}-experimental-${sha}`;
-const header = `Experimental Rescript WebAPI Documentation ${fullVersion}
+const header = `Experimental ReScript WebApi Documentation ${fullVersion}
 
-This is the API documentation for the experimental WebAPI module version ${fullVersion}.
+This is the API documentation for the experimental WebApi module version ${fullVersion}.
 More information can be found on https://rescript-lang.github.io/experimental-rescript-webapi/
 
 `;

package.json

@@ -1,7 +1,6 @@
 {
-  "name": "experimental-rescript-webapi",
+  "name": "@rescript/webapi",
   "version": "0.1.0",
-  "private": true,
   "description": "Experimental successor to [rescript-webapi](https://github.com/TheSpyder/rescript-webapi)",
   "keywords": [
     "dom",
@@ -23,8 +22,11 @@
     "type": "git",
     "url": "git+https://github.com/rescript-lang/experimental-rescript-webapi.git"
   },
-  "workspaces": [
-    "packages/*"
+  "files": [
+    "rescript.json",
+    "src/**/*.res",
+    "src/**/*.resi",
+    "README.md"
   ],
   "type": "module",
   "publishConfig": {
@@ -34,11 +36,9 @@
   "scripts": {
     "test": "node tests/index.js",
     "build": "rescript",
-    "build:packages": "npm run build --workspaces --if-present",
     "format": "rescript format && oxfmt ./tests/index.js ./package.json ./docs && prettier --write ./docs/pages",
     "format:check": "rescript format --check && oxfmt ./tests/index.js ./package.json ./docs --check && prettier --check ./docs/pages",
     "docs": "astro dev",
-    "create:npm-packages": "node scripts/create-npm-packages.js",
     "prebuild:docs": "node docs/llm.js",
     "build:docs": "astro build"
   },