@johnhenry/hydratable 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Henry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# hydratable
+
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fhydratable.svg)](https://www.npmjs.com/package/@johnhenry/hydratable)
+[![CI](https://github.com/johnhenry/hydratable/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/hydratable/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fhydratable.svg)](LICENSE)
+
+Full documentation: [opensource.johnhenry.me/hydratable](https://opensource.johnhenry.me/hydratable/)
+
+A generic async hydration mixin — `Hydratable(hydrateFn)` returns a
+prototype object you `Object.assign` onto a class's prototype, adding a
+guarded async `hydrate()` method. Also ships `mounts`, the companion this
+package also ships: framework-agnostic DOM mount-point helpers for handing
+React/Vue/Solid's render entrypoint a real element to mount into.
+
+No runtime dependencies. No build step — modules ship as source.
+
+## Install
+
+```bash
+npm install @johnhenry/hydratable
+```
+
+## `hydratable` — a generic async hydration mixin
+
+```js
+import Hydratable from "@johnhenry/hydratable/hydratable/index.mjs";
+
+const HPrototype = Hydratable(function ({ finalizer }) {
+  // `this` is the instance being hydrated. Define hydration here --
+  // this example computes and sets a derived property.
+  Object.defineProperty(this, "speed", {
+    value: this.distance / this.time,
+    writible: false,
+    enumerable: true,
+  });
+  // `finalizer` is optional -- if set, it runs *after* the hydrated flag
+  // is set, e.g. to freeze the object once hydration is complete.
+  finalizer(Object.freeze);
+});
+
+const object = Object.setPrototypeOf({ time: 1000, distance: 100 }, HPrototype);
+await object.hydrate();   // runs the hydrate function above
+await object.hydrate();   // idempotent -- already hydrated, returns immediately
+```
+
+`Hydratable(hydrateFn, name = "hydrate")` takes an optional second argument
+to change the generated method's name (e.g. `Hydratable(fn, "init")` adds
+`init()` instead of `hydrate()`).
+
+Two guards are built in:
+
+- **Double-hydration guard** — a `Symbol("hydrated")` flag is set on the
+  instance (not the shared prototype object) after the first successful
+  hydration; subsequent calls resolve immediately with `this`, without
+  re-running `hydrateFn`.
+- **Direct-prototype-call guard** — calling `hydrate()` directly on the
+  object returned by `Hydratable(...)` (rather than on something that
+  inherits from it) throws `Error: hydrate(...) must not be called from
+  prototype`. This catches the mistake of treating the mixin object itself
+  as an instance.
+
+See [`src/hydratable/demo.mjs`](src/hydratable/demo.mjs) for a full worked
+example, including both `Object.setPrototypeOf` and `Object.create` styles
+of attaching the mixin.
+
+## `mounts` — framework-agnostic DOM mount-point helpers
+
+Using `document.body` or one of its direct descendants as a mount point is
+a common pattern in modern JavaScript applications
+([Solid](https://www.solidjs.com/), [Vue](https://vuejs.org/),
+[React](https://reactjs.org/), etc.). `mounts` abstracts that away as
+plain imports, so a render call can hand a real element straight to
+React/Vue/Solid's entrypoint.
+
+```js
+import { render } from "solid-js/web";
+import Application from "./Solid-Application";
+import body from "@johnhenry/hydratable/mounts/body.mjs";
+render(() => <Application />, body);
+```
+
+```js
+import Application from "./Vue-Application";
+import first from "@johnhenry/hydratable/mounts/first.mjs";
+Application.mount(first);
+```
+
+```js
+import { createRoot } from "react-dom/client";
+import Application from "./React-Application";
+import last from "@johnhenry/hydratable/mounts/last.mjs";
+const root = createRoot(last);
+root.render(Application);
+```
+
+| Module | Description |
+|---|---|
+| [`mounts/body.mjs`](src/mounts/body.mjs) | `document.body` itself. Note: some frameworks (including React) warn against mounting directly onto `body` — prefer `first`/`last` instead. |
+| [`mounts/first.mjs`](src/mounts/first.mjs) | `document.body`'s first child, if it's a real, "suitable" element — otherwise a new `div` is created and prepended. |
+| [`mounts/last.mjs`](src/mounts/last.mjs) | `document.body`'s last child, if it's a real, "suitable" element — otherwise a new `div` is created and appended. |
+| [`mounts/unsuitable.mjs`](src/mounts/unsuitable.mjs) | The list of tag names `first`/`last` refuse to reuse as a mount point: `script`, `style`, `link`, `noscript`. |
+
+### Gotcha: `first.mjs`/`last.mjs` run at import time, not call time
+
+**`mounts/first.mjs` and `mounts/last.mjs` execute real DOM-reading code —
+`window.document.body.firstChild` / `.lastChild`, and potentially
+`document.createElement` + `prepend`/`append` — at module-evaluation time,
+directly in the module body, not inside an exported function.** The
+resolved (or newly created) element is the module's `default` export
+itself, computed once, the moment the module is first imported.
+
+This is deliberate, documented behavior, not a bug:
+
+- It means `document.body` must already exist and be in the state you
+  want inspected/mutated *before* you `import` either module — importing
+  it earlier than you intend (e.g. via a bundler hoisting imports, or a
+  barrel file) mutates the DOM at that earlier point instead.
+- It also means these two modules are effectively one-shot: importing
+  `first.mjs` a second time anywhere in the same module graph returns the
+  *same* cached export (ESM modules only evaluate once) — it will not
+  re-inspect the DOM or notice if `document.body`'s children changed since
+  the first import.
+- `mounts/body.mjs` does the same eager read (`window.document.body`) but
+  has no conditional logic, so the only consequence is that it can't be
+  imported before `document.body` exists.
+
+If you need the resolution logic to run lazily or more than once, don't
+import `first`/`last` directly for that — read their (tiny) source and
+adapt the pattern into a function you call when you actually want it
+evaluated.
+
+## Family
+
+- Originally extracted from [`johnhenry/lib`](https://github.com/johnhenry/lib)'s
+  `js/{mounts,hydratable}/0.0.0/` directories, then briefly part of
+  [`@johnhenry/domkit`](https://github.com/johnhenry/domkit) (a toolkit of
+  independent DOM/HTML-component modules). Both modules were documented in
+  domkit as companions to [`@johnhenry/domable`](https://github.com/johnhenry/domable)'s
+  DOM⇄React interop functions (`domToReact`/`reactToDom`) — convert a tree
+  to/from a React-element-shaped object with domable, then hand the
+  resulting rendered or converted tree to one of this package's `mounts`
+  helpers (or wrap the object in `hydratable`'s mixin) to actually mount it
+  into the page. Extracted again, out of domkit, into this standalone
+  package — the two modules form a real, coherent cluster on their own
+  (both concerned with getting a rendered/hydrated tree live in the page),
+  distinct from domkit's custom-element and shadow-DOM primitives.
+- [`@johnhenry/domkit`](https://github.com/johnhenry/domkit) — the
+  toolkit these two modules used to live in.
+- [`@johnhenry/domable`](https://github.com/johnhenry/domable) — DOM ⇄
+  text ⇄ React conversion primitives; `domToReact`/`reactToDom` pair
+  naturally with this package's `mounts`/`hydratable`, as described above.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@johnhenry/hydratable",
+  "version": "0.0.0",
+  "description": "A generic async hydration mixin, plus framework-agnostic DOM mount-point helpers for handing a mount element to React/Vue/Solid.",
+  "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node scripts/check-syntax.mjs && node test/import.test.mjs"
+  },
+  "keywords": [
+    "hydration",
+    "hydrate",
+    "dom",
+    "mount",
+    "ssr"
+  ],
+  "author": "John Henry",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/hydratable.git"
+  },
+  "homepage": "https://opensource.johnhenry.me/hydratable/",
+  "engines": {
+    "node": ">=26.0.0"
+  }
+}

package/src/hydratable/demo.mjs

@@ -0,0 +1,43 @@
+import Hydratable from "./index.mjs";
+let index = 0;
+const output = async (object) => {
+  console.log(index++);
+  console.log("initial object", object);
+  console.log("hydrated object", await object.hydrate()); // hydrate
+  await object.hydrate();
+  console.log("idempotency", object); // idempotent
+  console.log("keys", Object.keys(object));
+};
+const HPrototype = Hydratable(function ({ finalizer }) {
+  // here, hydration is defained as calculating and setting the speed property
+  Object.defineProperty(this, "speed", {
+    value: this.distance / this.time,
+    writible: false,
+    enumerable: true,
+  });
+  // also, we use the 'finalizer' optional argument to apply Object.freeze to the object AFTER setting the HYDRATED property
+  finalizer(Object.freeze);
+});
+// create object with minimal constraints
+const object = Object.setPrototypeOf(
+  {
+    time: 1000,
+    distance: 100,
+  },
+  HPrototype
+);
+await output(object);
+// create object with maximal constraints
+const object1 = Object.create(HPrototype, {
+  time: {
+    value: 1000,
+    writible: false,
+    enumerable: true,
+  },
+  distance: {
+    value: 100,
+    writible: false,
+    enumerable: true,
+  },
+});
+await output(object1);

package/src/hydratable/index.mjs

@@ -0,0 +1,39 @@
+const HYDRATED = Symbol("hydrated");
+const Hydratable = (hydrate, name = "hydrate") => {
+  const PRTOTOTYPE = {
+    async [name]() {
+      // should not be called directly on prototype object,
+      // but rather from inherritor
+      if (this.hasOwnProperty(name)) {
+        throw new Error(`${name}(...) must not be called from prototype`);
+      }
+      // return object if alreay hydrated
+      if (this[HYDRATED]) {
+        return this;
+      }
+      // finalize may be set during hydration
+      let finalize;
+      // perform hydratoion
+      await hydrate.call(this, {
+        finalizer: (func) => {
+          finalize = func;
+        },
+      });
+      // set HYDRATED flag
+      Object.defineProperty(this, HYDRATED, {
+        configurable: false,
+        value: true,
+        writible: false,
+      });
+      // apply finalize after hydration
+      if (typeof finalize === "function") {
+        await finalize.call(this, this);
+      }
+      // return hydrated object
+      return this;
+    },
+  };
+  return PRTOTOTYPE;
+};
+export default Hydratable;
+export { HYDRATED };

package/src/hydratable/readme.md

@@ -0,0 +1,7 @@
+# Hydratable
+
+Hydratable adds hydration functionality to objects in your prototype chain.
+
+## See also
+
+- [mounts](../mounts/readme.md) — framework-agnostic DOM mount-point helpers

package/src/mounts/body.mjs

@@ -0,0 +1 @@
+export default window.document.body;

package/src/mounts/first.mjs

@@ -0,0 +1,11 @@
+import unsuitable from "./unsuitable.mjs";
+let target = window.document.body.firstChild;
+if (
+  !target ||
+  target.nodeType !== Node.ELEMENT_NODE ||
+  unsuitable.includes(target.tagName.toLowerCase())
+) {
+  target = window.document.createElement("div");
+  window.document.body.prepend(target);
+}
+export default target;

package/src/mounts/last.mjs

@@ -0,0 +1,11 @@
+import unsuitable from "./unsuitable.mjs";
+let target = window.document.body.lastChild;
+if (
+  !target ||
+  target.nodeType !== Node.ELEMENT_NODE ||
+  unsuitable.includes(target.tagName.toLowerCase())
+) {
+  target = window.document.createElement("div");
+  window.document.body.append(target);
+}
+export default target;

package/src/mounts/readme.md

@@ -0,0 +1,65 @@
+# Mounts
+
+Using the body or its direct decendents
+as mount points is a common pattern
+in modern javascript applications ([Solid](https://www.solidjs.com/), [Vue](https://vuejs.org/), [React](https://reactjs.org/), etc.).
+
+We can declaratively abstract this away as imports.
+
+## Usage
+
+### Body
+
+Use body element as a mount point.
+
+Note: Some applications including react, warn against using the body element as a mount point.
+Use 'first' or 'last' instead.
+
+```javascript
+import { render } from "solid-js/web";
+import Application from "./Soild-Application";
+import body from "mounts/body.mjs";
+render(() => <Application />, body);
+```
+
+### First
+
+Use body's first child as a mount point.
+
+Creates and prepends a new 'div' element
+if child is "unsuitable" or non-existent.
+
+```javascript
+import Application from "./Vue-Application";
+import first from "mounts/first.mjs";
+Application.mount(first);
+```
+
+### Last
+
+Use body's last child as a mount point.
+
+Creates and appends a new 'div' element
+if child is "unsuitable" or non-existent.
+
+```javascript
+import { createRoot } from "react";
+import Application from "./React-Application";
+import last from "mounts/last.mjs";
+const root = createRoot(last);
+root.render(Application);
+```
+
+### Unsuitable elements
+
+The following elements are considered "unsuitable" for mounting:
+
+- script
+- style
+- link
+- noscript
+
+## See also
+
+- [`@johnhenry/domable`](https://github.com/johnhenry/domable)'s `domToReact`/`reactToDom` — converting between real DOM and React-element-shaped objects (domkit doesn't vendor its own copy of these; domable's is the maintained one)
+- [hydratable](../hydratable/readme.md) — a generic hydration mixin

package/src/mounts/unsuitable.mjs

@@ -0,0 +1 @@
+export default ["script", "style", "link", "noscript"];