ajo 0.1.29 → 0.1.31

package/html.js

@@ -0,0 +1,142 @@
+import { Context, current } from 'ajo/context'
+
+const Void = new Set(['area', 'base', 'br', 'col', 'command', 'embed', 'hr', 'img', 'input', 'keygen', 'link', 'meta', 'param', 'source', 'track', 'wbr'])
+
+const Args = Symbol.for('ajo.args')
+
+const escape = s => s.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`)
+
+const noop = () => { }
+
+export const render = h => [...html(h)].join('')
+
+export const html = function* (h) {
+
+	for (h of walk(h)) {
+
+		if (typeof h == 'string') yield escape(h)
+
+		else yield* element(h)
+	}
+}
+
+const element = function* ({ nodeName, children, ...h }) {
+
+	let attrs = ''
+
+	for (const key in h) {
+
+		if (key.startsWith('set:') || h[key] == null || h[key] === false) continue
+
+		if (h[key] === true) attrs += ` ${key}`
+
+		else attrs += ` ${key}="${escape(String(h[key]))}"`
+	}
+
+	if (Void.has(nodeName)) yield `<${nodeName}${attrs}>`
+
+	else {
+
+		yield `<${nodeName}${attrs}>`
+
+		if (children != null) yield* html(children)
+
+		yield `</${nodeName}>`
+	}
+}
+
+const walk = function* (h) {
+
+	if (h == null) return
+
+	const type = typeof h
+
+	if (type == 'boolean') return
+
+	if (type == 'string') yield h
+
+	else if (type == 'number' || type == 'bigint') yield String(h)
+
+	else if (Symbol.iterator in h) for (h of h) yield* walk(h)
+
+	else if ('nodeName' in h) typeof h.nodeName == 'function' ? yield* run(h) : yield vdom(h)
+
+	else yield String(h)
+}
+
+const run = function* ({ nodeName, fallback = nodeName.fallback, ...h }) {
+
+	if (nodeName.constructor.name == 'GeneratorFunction') yield runGenerator(nodeName, h)
+
+	else yield* walk(nodeName(h))
+}
+
+const runGenerator = (fn, h) => {
+
+	const attrs = { ...fn.attrs }, args = { ...fn.args }
+
+	for (const key in h) {
+
+		if (key.startsWith('attr:')) attrs[key.slice(5)] = h[key]
+
+		else if (key == 'key' || key == 'skip' || key == 'memo' || key == 'ref' || key.startsWith('set:')) attrs[key] = h[key]
+
+		else args[key] = h[key]
+	}
+
+	const controller = new AbortController()
+
+	const instance = {
+
+		[Context]: Object.create(current()?.[Context] ?? null),
+
+		[Args]: args,
+
+		signal: controller.signal,
+
+		next: noop,
+
+		return: noop,
+
+		throw: value => { throw value }
+	}
+
+	const iterator = fn.call(instance, args)
+
+	const parent = current()
+
+	current(instance)
+
+	const result = children => ({ ...attrs, nodeName: fn.is ?? 'div', ...vdom({ children }) })
+
+	try {
+
+		return result(iterator.next().value)
+
+	} catch (error) {
+
+		return result(iterator.throw(error).value)
+
+	} finally {
+
+		iterator.return()
+
+		controller.abort()
+
+		current(parent)
+	}
+}
+
+const vdom = ({ key, skip, memo, ref, ...h }) => {
+
+	if ('children' in h) {
+
+		const children = [...walk(h.children)]
+
+		if (children.length) h.children = children.length == 1 ? children[0] : children
+
+		else delete h.children
+	}
+
+	return h
+}

package/index.js

@@ -0,0 +1,286 @@
+import { Context, current } from 'ajo/context'
+
+const Key = Symbol.for('ajo.key')
+const Memo = Symbol.for('ajo.memo')
+const Ref = Symbol.for('ajo.ref')
+const Cache = Symbol.for('ajo.cache')
+const Generator = Symbol.for('ajo.generator')
+const Iterator = Symbol.for('ajo.iterator')
+const Render = Symbol.for('ajo.render')
+const Args = Symbol.for('ajo.args')
+const Controller = Symbol.for('ajo.controller')
+
+export const Fragment = props => props.children
+
+export const h = (type, props, ...children) => {
+
+	(props ??= {}).nodeName = type
+
+	if (!('children' in props) && children.length) props.children = children.length == 1 ? children[0] : children
+
+	return props
+}
+
+export const render = (h, el, child = el.firstChild, ref = null) => {
+
+	for (h of walk(h)) {
+
+		const node = reconcile(h, el, child)
+
+		if (child == null) {
+
+			before(el, node, ref)
+
+		} else if (node == child) {
+
+			child = node.nextSibling
+
+		} else if (node == child.nextSibling) {
+
+			before(el, child, ref)
+
+			child = node.nextSibling
+
+		} else {
+
+			before(el, node, child)
+		}
+	}
+
+	while (child != ref) {
+
+		const node = child.nextSibling
+
+		if (child.nodeType == 1) unref(child)
+
+		el.removeChild(child)
+
+		child = node
+	}
+}
+
+const walk = function* (h) {
+
+	if (h == null) return
+
+	const type = typeof h
+
+	if (type == 'boolean') return
+
+	if (type == 'string') yield h
+
+	else if (type == 'number' || type == 'bigint') yield String(h)
+
+	else if (Symbol.iterator in h) for (h of h) yield* walk(h)
+
+	else if ('nodeName' in h) typeof h.nodeName == 'function' ? yield* run(h) : yield h
+
+	else yield String(h)
+}
+
+const run = function* ({ nodeName, ...h }) {
+
+	if (nodeName.constructor.name == 'GeneratorFunction') yield runGenerator(nodeName, h)
+
+	else yield* walk(nodeName(h))
+}
+
+const runGenerator = (fn, h) => {
+
+	const attrs = { ...fn.attrs }, args = { ...fn.args }
+
+	for (const key in h) {
+
+		if (key.startsWith('attr:')) attrs[key.slice(5)] = h[key]
+
+		else if (key == 'key' || key == 'skip' || key == 'memo' || key == 'ref' || key.startsWith('set:')) attrs[key] = h[key]
+
+		else args[key] = h[key]
+	}
+
+	return { ...attrs, nodeName: fn.is ?? 'div', [Generator]: fn, [Args]: args }
+}
+
+const reconcile = (h, el, node) => typeof h == 'string' ? text(h, node) : element(h, el, node)
+
+const text = (h, node) => {
+
+	while (node && node.nodeType != 3) node = node.nextSibling
+
+	node ? node.data != h && (node.data = h) : node = document.createTextNode(h)
+
+	return node
+}
+
+const element = ({ nodeName, children, key, skip, memo, ref, [Generator]: gen, [Args]: args, ...h }, el, node) => {
+
+	while (node && (
+
+		(node.localName != nodeName) ||
+
+		(node[Key] != null && node[Key] != key) ||
+
+		(node[Generator] && node[Generator] != gen)
+
+	)) node = node.nextSibling
+
+	node ??= document.createElementNS(h.xmlns ?? el.namespaceURI, nodeName)
+
+	if (key != null) node[Key] = key
+
+	if (memo == null || some(node[Memo], node[Memo] = memo)) {
+
+		attrs(node[Cache] ?? extract(node), node[Cache] = h, node)
+
+		if (!skip) gen ? next(gen, args, node) : render(children, node)
+
+		if (typeof ref == 'function') (node[Ref] = ref)(node)
+	}
+
+	return node
+}
+
+const attrs = (cache, h, node) => {
+
+	for (const key in { ...cache, ...h }) {
+
+		if (cache[key] === h[key]) continue
+
+		if (key.startsWith('set:')) node[key.slice(4)] = h[key]
+
+		else if (h[key] == null || h[key] === false) node.removeAttribute(key)
+
+		else node.setAttribute(key, h[key] === true ? '' : h[key])
+	}
+}
+
+const some = (a, b) => Array.isArray(a) && Array.isArray(b) ? a.some((v, i) => v !== b[i]) : a !== b
+
+const extract = el => Array.from(el.attributes).reduce((out, attr) => (out[attr.name] = attr.value, out), {})
+
+const before = (el, node, child) => {
+
+	if (node.contains(document.activeElement)) {
+
+		const ref = node.nextSibling
+
+		while (child && child != node) {
+
+			const next = child.nextSibling
+
+			el.insertBefore(child, ref)
+
+			child = next
+		}
+
+	} else el.insertBefore(node, child)
+}
+
+const unref = node => {
+
+	for (const child of node.children) unref(child)
+
+	if (typeof node.return == 'function') node.return()
+
+	node[Ref]?.(null)
+}
+
+const next = (fn, args, el) => {
+
+	el[Generator] ??= (attach(el), fn)
+
+	Object.assign(el[Args] ??= {}, args)
+
+	el[Render]()
+}
+
+const attach = el => {
+
+	Object.assign(el, methods)
+
+	el[Context] = Object.create(current()?.[Context] ?? null)
+}
+
+const methods = {
+
+	[Render]() {
+
+		const parent = current()
+
+		current(this)
+
+		try {
+
+			if (!this[Iterator]) {
+
+				this.signal = (this[Controller] = new AbortController()).signal
+
+				this[Iterator] = this[Generator].call(this, this[Args])
+			}
+
+			const { value, done } = this[Iterator].next()
+
+			render(value, this)
+
+			this[Ref]?.(this)
+
+			if (done) this.return()
+
+		} catch (e) {
+
+			this.throw(e)
+
+		} finally {
+
+			current(parent)
+		}
+	},
+
+	next(fn, result) {
+
+		try {
+
+			if (typeof fn == 'function') result = fn.call(this, this[Args])
+
+		} catch (e) {
+
+			return this.throw(e)
+		}
+
+		if (!current()?.contains(this)) this[Render]()
+
+		return result
+	},
+
+	throw(value) {
+
+		for (let el = this; el; el = el.parentNode) if (el[Iterator]?.throw) try {
+
+			return render(el[Iterator].throw(value).value, el)
+
+		} catch (e) {
+
+			value = new Error(e?.message ?? e, { cause: value })
+		}
+
+		throw value
+	},
+
+	return() {
+
+		try {
+
+			this[Iterator]?.return()
+
+		} catch (e) {
+
+			this.throw(e)
+
+		} finally {
+
+			this[Iterator] = null
+
+			this[Controller]?.abort()
+		}
+	}
+}

package/license

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2022-2025, Cristian Falcone
+Copyright (c) 2022-2026, Cristian Falcone
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ajo",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "ajo is a JavaScript view library for building user interfaces",
   "type": "module",
   "types": "./types.ts",
@@ -21,23 +21,22 @@
       "types": "./types.ts",
       "import": "./dist/html.js",
       "require": "./dist/html.cjs"
-    },
-    "./stream": {
-      "types": "./types.ts",
-      "import": "./dist/stream.js",
-      "require": "./dist/stream.cjs"
     }
   },
   "files": [
     "dist",
+    "context.js",
+    "html.js",
+    "index.js",
+    "LLMs.md",
     "types.ts"
   ],
   "devDependencies": {
-    "@types/node": "25.0.9",
-    "happy-dom": "20.3.1",
+    "@types/node": "25.2.3",
+    "happy-dom": "20.6.1",
     "vite": "7.3.1",
-    "vite-tsconfig-paths": "6.0.4",
-    "vitest": "4.0.17"
+    "vite-tsconfig-paths": "6.1.1",
+    "vitest": "4.0.18"
   },
   "keywords": [
     "ui",

package/readme.md

@@ -13,11 +13,10 @@
   </a>
 </div>
 
-A modern JavaScript library for building user interfaces with generator-based state management, efficient DOM updates, and streaming server-side rendering.
+A modern JavaScript library for building user interfaces with generator-based state management and efficient DOM updates.
 
 - **Generator-Based Components**: Use `function*` for stateful components with built-in lifecycle
 - **Efficient DOM Updates**: In-place reconciliation minimizes DOM manipulation
-- **Streaming SSR**: Progressive rendering with selective hydration (islands)
 
 ## Quick Start
 
@@ -29,6 +28,7 @@ npm install ajo
 import { render } from 'ajo'
 
 function* Counter() {
+
   let count = 0
 
   while (true) yield (
@@ -91,6 +91,7 @@ Generator functions with automatic wrapper elements. The structure provides a na
 
 ```javascript
 function* TodoList() {
+
   let todos = []
   let text = ''
 
@@ -102,6 +103,7 @@ function* TodoList() {
   })
 
   while (true) {
+
     const count = todos.length
 
     yield (
@@ -123,10 +125,11 @@ function* TodoList() {
 
 ### Re-rendering with `this.next()`
 
-Call `this.next()` to trigger a re-render. The optional callback receives current props, useful when props may have changed:
+Call `this.next()` to trigger a re-render. The optional callback receives current props and its return value is passed through:
 
 ```javascript
 function* Stepper(args) {
+
   let count = 0
 
   // Access current props in callback
@@ -155,11 +158,28 @@ function* Good(args) {
 
 ### Lifecycle and Cleanup
 
-Use `try...finally` for cleanup when the component unmounts:
+Every stateful component has a `this.signal` (AbortSignal) that aborts when the component unmounts. Use it with any API that accepts a signal:
+
+```javascript
+function* MouseTracker() {
+
+  let pos = { x: 0, y: 0 }
+
+  document.addEventListener('mousemove', e => this.next(() => {
+    pos = { x: e.clientX, y: e.clientY }
+  }), { signal: this.signal }) // auto-removed on unmount
+
+  while (true) yield <p>{pos.x}, {pos.y}</p>
+}
+```
+
+For APIs that don't accept a signal, use `try...finally`:
 
 ```javascript
 function* Clock() {
+
   let time = new Date()
+
   const interval = setInterval(() => this.next(() => time = new Date()), 1000)
 
   try {
@@ -223,6 +243,7 @@ function* ErrorBoundary(args) {
 
 ```javascript
 function* AutoFocus() {
+
   let input = null
 
   while (true) yield (
@@ -251,6 +272,7 @@ timer?.next()  // trigger re-render from outside
 
 ```javascript
 function* Chart(args) {
+
   let chart = null
 
   while (true) yield (
@@ -292,6 +314,7 @@ const Card = ({ title }) => {
 
 // Stateful - write inside loop (updates each render)
 function* ThemeProvider(args) {
+
   let theme = 'light'
 
   while (true) {
@@ -318,9 +341,10 @@ function* FixedTheme(args) {
 
 ```javascript
 function* UserProfile(args) {
+
   let data = null, error = null, loading = true
 
-  fetch(`/api/users/${args.id}`)
+  fetch(`/api/users/${args.id}`, { signal: this.signal })
     .then(r => r.json())
     .then(d => this.next(() => { data = d; loading = false }))
     .catch(e => this.next(() => { error = e; loading = false }))
@@ -336,41 +360,8 @@ function* UserProfile(args) {
 ## Server-Side Rendering
 
 ```javascript
-// Static
 import { render } from 'ajo/html'
 const html = render(<App />)
-
-// Streaming
-import { stream } from 'ajo/stream'
-for await (const chunk of stream(<App />)) res.write(chunk)
-
-// Hydration (client-side)
-import { hydrate } from 'ajo/stream'
-window.$stream = { push: hydrate }
-```
-
-### Islands Architecture
-
-```javascript
-function* Interactive() {
-  let count = 0
-  while (true) yield (
-    <button set:onclick={() => this.next(() => count++)}>
-      {count}
-    </button>
-  )
-}
-
-Interactive.src = '/islands/interactive.js'  // hydrate on client
-
-const Page = () => (
-  <html>
-    <body>
-      <p>Static content</p>
-      <Interactive fallback={<button>0</button>} />
-    </body>
-  </html>
-)
 ```
 
 ## TypeScript
@@ -388,6 +379,7 @@ const Card: Stateless<CardProps> = ({ title, children }) => (
 type CounterProps = { initial: number; step?: number }
 
 const Counter: Stateful<CounterProps, 'section'> = function* (args) {
+
   let count = args.initial
 
   while (true) {
@@ -423,16 +415,11 @@ let ref: ThisParameterType<typeof Counter> | null = null
 |--------|-------------|
 | `render(children)` | Render to HTML string |
 
-### `ajo/stream`
-| Export | Description |
-|--------|-------------|
-| `stream(children)` | Async iterator for streaming SSR |
-| `hydrate(patch)` | Apply streamed patch on client |
-
 ### Stateful `this`
-| Method | Description |
-|--------|-------------|
-| `this.next(fn?)` | Re-render. Callback receives current args. |
+| Property | Description |
+|----------|-------------|
+| `this.signal` | AbortSignal that aborts on unmount. Pass to `fetch()`, `addEventListener()`, etc. |
+| `this.next(fn?)` | Re-render. Callback receives current args. Returns callback's result. |
 | `this.throw(error)` | Throw to parent boundary |
 | `this.return()` | Terminate generator |
 

package/types.ts

@@ -53,7 +53,8 @@ declare module 'ajo' {
 		TArguments
 
 	type StatefulElement<TArguments, TTag> = ElementType<TTag> & {
-		next: (fn?: (this: StatefulElement<TArguments, TTag>, args: StatefulArgs<TArguments, TTag>) => void) => void,
+		signal: AbortSignal,
+		next: <R>(fn?: (this: StatefulElement<TArguments, TTag>, args: StatefulArgs<TArguments, TTag>) => R) => R,
 		throw: (value?: unknown) => void,
 		return: () => void,
 	}
@@ -80,27 +81,8 @@ declare module 'ajo/context' {
 }
 
 declare module 'ajo/html' {
-
-	type Patch = {
-		id: string,
-		h: import('ajo').Children,
-		src?: string,
-		done: boolean,
-	}
-
-	type Hooks = {
-		alloc?: (parentId: string) => string,
-		placeholder?: (id: string, children: import('ajo').Children) => unknown,
-		push?: (patch: Patch) => void,
-	}
-
 	function render(h: import('ajo').Children): string
-	function html(h: import('ajo').Children, hooks?: Hooks): IterableIterator<string>
-}
-
-declare module 'ajo/stream' {
-	function stream(h: import('ajo').Children): AsyncIterableIterator<string>
-	function hydrate(patch: import('ajo/html').Patch): Promise<void>
+	function html(h: import('ajo').Children): IterableIterator<string>
 }
 
 declare namespace JSX {

package/dist/stream.cjs

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("./index.cjs"),m=require("./html.cjs"),y=async function*(o,n=""){const s=new Map([[n,0]]),t=new Set,i=[],r=(e=n)=>(s.set(e,(s.get(e)??0)+1),e?`${e}:${s.get(e)-1}`:String(s.get(e)-1)),h=(e,c)=>({nodeName:"div","data-ssr":e,children:c}),f=e=>{const c=Promise.resolve(`<script>window.$stream?.push(${JSON.stringify(e)})<\/script>`);t.add(c),c.then(u=>i.push(u)).finally(()=>t.delete(c))};for(const e of m.html(o,{alloc:r,placeholder:h,push:f}))yield e;for(;t.size||i.length;){for(;i.length;)yield i.shift();t.size&&await Promise.race(t)}},d=new Set;async function l({id:o,src:n,h:s}){const t=document.querySelector(`[data-ssr="${o}"]`);if(!t)return d.add({id:o,src:n,h:s});n?a.render(a.h((await import(n)).default,s),t):a.render(s,t);const i=o+":";for(const r of d)r.id.startsWith(i)&&(d.delete(r),l(r))}exports.hydrate=l;exports.stream=y;