@barefootjs/cli 0.5.1 → 0.5.2

package/dist/docs/core/llms.txt

@@ -12,6 +12,7 @@
 
 ## Reactivity
 
+- [batch](https://barefootjs.dev/docs/reactivity/batch.md): Groups multiple signal writes so dependent effects and memos run once, after all writes complete.
 - [createEffect](https://barefootjs.dev/docs/reactivity/create-effect.md): Runs a function and re-runs it whenever its tracked signal dependencies change.
 - [createMemo](https://barefootjs.dev/docs/reactivity/create-memo.md): Creates a cached derived value that recomputes only when its dependencies change.
 - [createSignal](https://barefootjs.dev/docs/reactivity/create-signal.md): Creates a reactive getter/setter pair for managing state.

package/dist/docs/core/reactivity/batch.md

@@ -0,0 +1,135 @@
+---
+title: batch
+description: Groups multiple signal writes so dependent effects and memos run once, after all writes complete.
+---
+
+# batch
+
+Groups multiple signal writes so that dependent effects and memos run **once**,
+after all the writes inside the batch complete — instead of once per write.
+
+```tsx
+import { batch } from '@barefootjs/client'
+
+batch<T>(fn: () => T): T
+```
+
+Returns the value produced by `fn`.
+
+## Default behavior (no batch)
+
+BarefootJS propagates updates **synchronously**: each setter call immediately
+re-runs every subscriber. This keeps reads-after-writes predictable — after a
+setter returns, derived memos, effects, and the DOM already reflect the new value.
+
+The cost is that writing N signals that share a subscriber re-runs that
+subscriber N times, and the subscriber briefly observes intermediate states
+where some signals are updated and others are not:
+
+```tsx
+const [x, setX] = createSignal(40)
+const [y, setY] = createSignal(60)
+
+createEffect(() => {
+  // depends on both x and y
+  send({ x: x(), y: y() })
+})
+
+setX(70) // effect runs — observes x=70, y=60 (intermediate)
+setY(30) // effect runs again — observes x=70, y=30
+```
+
+Beyond its initial run on creation, the effect ran twice more — once per write —
+and saw a transient `x=70, y=60` state.
+
+## With batch
+
+```tsx
+batch(() => {
+  setX(70)
+  setY(30)
+})
+// effect runs once, observing x=70, y=30
+```
+
+Inside `batch`, writes are collected and dependent subscribers are de-duplicated,
+so each runs **exactly once** after the batch ends — and never observes an
+intermediate, half-updated state.
+
+## When to use
+
+When a single handler updates several signals that feed shared effects/memos,
+`batch` collapses the work into one update pass — and keeps the subscriber from
+running while a cross-field invariant is temporarily broken:
+
+```tsx
+const reset = () => {
+  batch(() => {
+    setName('')
+    setEmail('')
+    setAge(0)
+    // ...20 more fields
+  })
+  // every subscriber ran once, not once-per-field
+}
+```
+
+## Caveats
+
+### Derived values are stale *inside* the batch
+
+`batch` defers the work that recomputes derived values. Plain signal reads return
+the new value immediately, but **memos and effect-driven values stay stale until
+the batch ends**:
+
+```tsx
+const [n, setN] = createSignal(1)
+const doubled = createMemo(() => n() * 2)
+
+batch(() => {
+  setN(10)
+  n()       // 10  — plain signal read is fresh
+  doubled() // 2   — STALE; the memo hasn't recomputed yet
+})
+doubled()   // 20  — recomputed after the batch ends
+```
+
+If you need the recomputed value, read it after the batch.
+
+### `await` escapes the batch
+
+`batch` only covers the **synchronous** portion of `fn`. Wrapping an async
+function in `batch` groups only the writes before the first `await` — everything
+after runs ungrouped, and the promise `batch` returns is easy to leave floating.
+
+Instead, wrap each synchronous group of writes in its own `batch`, with `await`
+between the groups:
+
+```tsx
+const onSubmit = async () => {
+  batch(() => {
+    setLoading(true)
+    setError(null)
+  })
+
+  try {
+    const result = await save()
+    batch(() => {
+      setLoading(false)
+      setResult(result)
+    })
+  } catch (err) {
+    batch(() => {
+      setLoading(false)
+      setError(err)
+    })
+  }
+}
+```
+
+## Note
+
+`batch` is an **opt-in** optimization. Forgetting it is never a correctness bug —
+code still works, just with extra subscriber runs. Reach for `batch` when a
+handler writes many signals that share subscribers, or when an effect must not
+observe a partially-updated state.

package/dist/docs/core/reactivity.md

@@ -9,7 +9,7 @@ All reactive primitives are imported from `@barefootjs/client`:
 
 ```tsx
 "use client"
-import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack } from '@barefootjs/client'
+import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack, batch } from '@barefootjs/client'
 ```
 
 ## API Reference
@@ -22,6 +22,7 @@ import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack } f
 | [`onMount`](./reactivity/on-mount.md) | Run once on component initialization |
 | [`onCleanup`](./reactivity/on-cleanup.md) | Register cleanup for effects and lifecycle |
 | [`untrack`](./reactivity/untrack.md) | Read signals without tracking dependencies |
+| [`batch`](./reactivity/batch.md) | Group signal writes so subscribers run once |
 
 ## Guides
 

package/dist/index.js

@@ -2450,6 +2450,24 @@ function getSourceLocation(node, sourceFile, filePath) {
     }
   };
 }
+function membersToProperties(members, sourceFile) {
+  return members.filter(ts6.isPropertySignature).map((member) => ({
+    name: propertyNameText(member.name, sourceFile),
+    type: typeNodeToTypeInfo(member.type, sourceFile) ?? {
+      kind: "unknown",
+      raw: "unknown"
+    },
+    optional: !!member.questionToken,
+    readonly: !!member.modifiers?.some(
+      (m) => m.kind === ts6.SyntaxKind.ReadonlyKeyword
+    )
+  }));
+}
+function propertyNameText(name, sourceFile) {
+  if (!name) return "";
+  if (ts6.isStringLiteral(name) || ts6.isNumericLiteral(name)) return name.text;
+  return name.getText(sourceFile);
+}
 function typeNodeToTypeInfo(typeNode, sourceFile) {
   if (!typeNode) return null;
   const raw = typeNode.getText(sourceFile);
@@ -2488,20 +2506,21 @@ function typeNodeToTypeInfo(typeNode, sourceFile) {
     return {
       kind: "object",
       raw,
-      properties: typeNode.members.filter(ts6.isPropertySignature).map((member) => ({
-        name: member.name?.getText(sourceFile) ?? "",
-        type: typeNodeToTypeInfo(member.type, sourceFile) ?? {
-          kind: "unknown",
-          raw: "unknown"
-        },
-        optional: !!member.questionToken,
-        readonly: !!member.modifiers?.some(
-          (m) => m.kind === ts6.SyntaxKind.ReadonlyKeyword
-        )
-      }))
+      properties: membersToProperties(typeNode.members, sourceFile)
     };
   }
   if (ts6.isTypeReferenceNode(typeNode)) {
+    const refName = ts6.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : "";
+    if ((refName === "Array" || refName === "ReadonlyArray") && typeNode.typeArguments?.length === 1) {
+      return {
+        kind: "array",
+        raw,
+        elementType: typeNodeToTypeInfo(typeNode.typeArguments[0], sourceFile) ?? {
+          kind: "unknown",
+          raw: "unknown"
+        }
+      };
+    }
     return {
       kind: "interface",
       raw
@@ -3679,14 +3698,17 @@ function collectInterfaceDefinition(node, ctx2) {
     kind: "interface",
     name: node.name.text,
     definition: node.getText(ctx2.sourceFile),
+    properties: membersToProperties(node.members, ctx2.sourceFile),
     loc: getSourceLocation(node, ctx2.sourceFile, ctx2.filePath)
   });
 }
 function collectTypeAliasDefinition(node, ctx2) {
+  const properties = ts7.isTypeLiteralNode(node.type) ? membersToProperties(node.type.members, ctx2.sourceFile) : void 0;
   ctx2.typeDefinitions.push({
     kind: "type",
     name: node.name.text,
     definition: node.getText(ctx2.sourceFile),
+    properties,
     loc: getSourceLocation(node, ctx2.sourceFile, ctx2.filePath)
   });
 }
@@ -5882,7 +5904,7 @@ function checkSupport(expr) {
           return {
             supported: false,
             level: "L5_UNSUPPORTED",
-            reason: `Higher-order method '${methodName}()' requires client-side evaluation. Use @client directive or pre-compute in Go.`
+            reason: `Method '${methodName}()' has no template lowering and requires client-side evaluation. Wrap the expression in /* @client */ to defer it to hydration, or pre-compute the value before rendering.`
           };
         }
       }
@@ -6172,7 +6194,7 @@ var init_expression_parser = __esm({
       "some",
       "forEach",
       "flatMap",
-      "flat"
+      "flat",
       // #1448 Tier A — Array methods. Each method PR adds the lowering
       // (typically a new `array-method` variant or runtime helper) and
       // removes its row here. See packages/adapter-tests/fixtures/methods/.
@@ -6202,6 +6224,34 @@ var init_expression_parser = __esm({
       // `bf_lower` / `bf_upper` (Go) and Perl's native `lc` / `uc` (Mojo).
       // `trim` lowers via the `array-method` IR + `bf_trim` (Go) and a
       // Perl regex strip (Mojo).
+      //
+      // #1448 follow-up — String methods that have NO lowering yet. These
+      // were previously absent from this gate, so `isSupported` reported
+      // them "supported" and the adapters emitted a raw method call
+      // (`{{.Name.StartsWith "a"}}` on Go, `$name->{startsWith}('a')` on
+      // Mojo) with no build diagnostic — a silent footgun that only
+      // surfaced as a crash at template-render time. Listing them here
+      // makes the build fail loudly with BF101 (the same treatment the
+      // unsupported array methods above get), pointing users at the
+      // `/* @client */` escape hatch. Each name drops off as its lowering
+      // lands. See #1448 "Unsupported string methods" Tier B / Tier C.
+      "split",
+      "startsWith",
+      "endsWith",
+      "replace",
+      "replaceAll",
+      "repeat",
+      "padStart",
+      "padEnd",
+      "charAt",
+      "charCodeAt",
+      "codePointAt",
+      "normalize",
+      "substring",
+      "substr",
+      "match",
+      "matchAll",
+      "search"
     ]);
   }
 });
@@ -9545,21 +9595,30 @@ function producesDomChild(node) {
 }
 function computeLoopSiblingOffsets(root) {
   const offsets = /* @__PURE__ */ new Map();
-  walkIR(root, null, {
-    element: ({ node: el, descend }) => {
-      let nonLoopCount = 0;
-      for (const child of el.children) {
-        if (child.type === "loop") {
-          if (nonLoopCount > 0) offsets.set(child, nonLoopCount);
-        } else if (producesDomChild(child)) {
-          nonLoopCount++;
-        }
+  const recordChildren = (children) => {
+    let nonLoopCount = 0;
+    for (const child of children) {
+      if (child.type === "loop") {
+        if (nonLoopCount > 0) offsets.set(child, nonLoopCount);
+      } else if (producesDomChild(child)) {
+        nonLoopCount++;
       }
-      descend();
     }
-    // All container kinds (fragment / component / provider / async / loop /
-    // conditional / if-statement) rely on walkIR's default descent with the
-    // same scope. Leaves (text / expression / slot) are no-ops.
+  };
+  const containerVisit = ({ node, descend }) => {
+    recordChildren(node.children);
+    descend();
+  };
+  walkIR(root, null, {
+    element: containerVisit,
+    component: containerVisit,
+    fragment: containerVisit,
+    provider: containerVisit,
+    async: containerVisit
+    // `loop` / `conditional` / `if-statement` are not flat sibling
+    // containers (their children are item bodies / branches), and leaves
+    // (text / expression / slot) have no children — all rely on walkIR's
+    // default descent with the same scope.
   });
   return offsets;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/cli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "CLI for agent-driven UI component discovery and scaffolding",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
     "typescript": "^5.0.0"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.5.1",
+    "@barefootjs/jsx": "0.5.2",
     "@types/node": "^22.0.0"
   }
 }