@ilha/router 0.10.4 → 0.11.0

package/oxlint.cjs

@@ -1,6 +1,6 @@
-const PASCAL_CASE = /^[A-Z][a-zA-Z0-9]*$/;
-const PRIMITIVES = new Set(["state", "derived", "action", "effect", "onError"]);
-const ACTION_STATUS = new Set(["pending", "data", "error"]);
+const PRIMITIVES = new Set(["atom", "when", "watch", "wait"]);
+// when/watch/wait return Instructions — they are only consumable by a generator frame.
+const INSTRUCTIONS = new Set(["when", "watch", "wait"]);
 const CONDITIONAL = new Set([
   "IfStatement",
   "ForStatement",
@@ -15,63 +15,21 @@ const CONDITIONAL = new Set([
 const FN_TYPES = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
 
 function bindings() {
-  return { ilha: new Set(["ilha"]), prim: new Map() };
+  return { prim: new Map() };
 }
 
 function takeImport(b, node) {
   if (node.source.value !== "ilha") return;
   for (const s of node.specifiers) {
     if (s.type !== "ImportSpecifier") continue;
-    const imported = s.imported.name;
-    const local = s.local.name;
-    if (imported === "ilha") {
-      b.ilha.add(local);
-    }
-    if (PRIMITIVES.has(imported)) b.prim.set(local, imported);
+    if (PRIMITIVES.has(s.imported.name)) b.prim.set(s.local.name, s.imported.name);
   }
 }
 
-function isIlhaCall(node, b) {
-  return (
-    node.type === "CallExpression" &&
-    node.callee.type === "Identifier" &&
-    b.ilha.has(node.callee.name)
-  );
-}
-
 function primitiveName(node, b) {
   if (node.type !== "CallExpression") return null;
-  const c = node.callee;
-  if (c.type === "Identifier") return b.prim.get(c.name) ?? null;
-  const effectLocal = [...b.prim].find(([, n]) => n === "effect")?.[0];
-  if (
-    effectLocal &&
-    c.type === "MemberExpression" &&
-    !c.computed &&
-    c.object.type === "Identifier" &&
-    c.object.name === effectLocal &&
-    c.property.type === "Identifier" &&
-    c.property.name === "once"
-  ) {
-    return "effect.once";
-  }
-  return null;
-}
-
-function fnName(node, parent) {
-  if (node.id && node.id.type === "Identifier") return node.id.name;
-  if (parent?.type === "VariableDeclarator" && parent.id.type === "Identifier") {
-    return parent.id.name;
-  }
-  return "";
-}
-
-function isComponentFn(node, parent, ancestors, b) {
-  const name = fnName(node, parent);
-  if (PASCAL_CASE.test(name)) return true;
-  if (parent?.type === "CallExpression" && isIlhaCall(parent, b)) return true;
-  const grand = ancestors?.[ancestors.length - 2];
-  return !!(grand && isIlhaCall(grand, b));
+  if (node.callee.type !== "Identifier") return null;
+  return b.prim.get(node.callee.name) ?? null;
 }
 
 function ancestorsOf(context, node) {
@@ -80,90 +38,21 @@ function ancestorsOf(context, node) {
   return [];
 }
 
-function parentOf(context, node) {
-  const a = ancestorsOf(context, node);
-  return a[a.length - 1];
-}
-
-function toPascalCase(name) {
-  return name.charAt(0).toUpperCase() + name.slice(1);
-}
-
 function calleeName(node) {
   return node.type === "Identifier" ? node.name : null;
 }
 
-function collectIslands(b) {
-  const names = new Set();
-  return {
-    names,
-    VariableDeclarator(node) {
-      if (node.id.type === "Identifier" && node.init && isIlhaCall(node.init, b)) {
-        names.add(node.id.name);
-      }
-    },
-  };
+function enclosingFunctions(ancestors) {
+  return ancestors.filter((a) => FN_TYPES.has(a.type));
 }
 
-function isInsideComponent(context, node, b) {
-  const ancestors = ancestorsOf(context, node);
-  for (let i = ancestors.length - 1; i >= 0; i--) {
-    const a = ancestors[i];
-    if (!FN_TYPES.has(a.type)) continue;
-    const parent = i > 0 ? ancestors[i - 1] : null;
-    if (isComponentFn(a, parent, ancestors.slice(0, i), b)) return true;
-  }
-  return false;
-}
-
-function islandCallee(names, callee) {
-  if (callee.type === "Identifier" && names.has(callee.name)) return callee.name;
-  return null;
-}
-
-const pascalCase = {
-  meta: {
-    type: "suggestion",
-    fixable: "code",
-    docs: { description: "Enforce PascalCase for ilha island variable names" },
-    messages: {
-      notPascalCase: 'Island variable "{{name}}" must be PascalCase (e.g. "{{suggested}}").',
-    },
-    schema: [],
-  },
-  create(context) {
-    const b = bindings();
-    return {
-      ImportDeclaration(node) {
-        takeImport(b, node);
-      },
-      VariableDeclarator(node) {
-        if (node.id.type === "Identifier" && node.init && isIlhaCall(node.init, b)) {
-          const name = node.id.name;
-          if (!PASCAL_CASE.test(name)) {
-            const suggested = toPascalCase(name);
-            context.report({
-              node: node.id,
-              messageId: "notPascalCase",
-              data: { name, suggested },
-              fix(fixer) {
-                return fixer.replaceText(node.id, suggested);
-              },
-            });
-          }
-        }
-      },
-    };
-  },
-};
-
 const noConditionalPrimitive = {
   meta: {
     type: "problem",
-    docs: { description: "Disallow primitives inside conditionals or loops" },
+    docs: { description: "Disallow atom/when/watch/wait inside conditionals or loops" },
     messages: {
       conditional:
-        "Do not call {{name}}() inside a condition or loop. Put the branch inside the primitive.",
+        "Do not call {{name}}() inside a condition or loop. Primitive registration order must be stable — put the branch inside the primitive or the view.",
     },
     schema: [],
   },
@@ -190,13 +79,15 @@ const noConditionalPrimitive = {
   },
 };
 
-const noPrimitiveOutsideIsland = {
+const noPrimitiveOutsideComponent = {
   meta: {
     type: "problem",
-    docs: { description: "Only call primitives in an island render or PascalCase component" },
+    docs: {
+      description: "Call atom/when/watch/wait inside a component, never at module top level",
+    },
     messages: {
       outside:
-        "Call {{name}}() only in an ilha() render or a PascalCase component. Put setup in effect.once().",
+        "Call {{name}}() inside a component. There is no fiber at module scope, so this throws at runtime.",
     },
     schema: [],
   },
@@ -210,52 +101,51 @@ const noPrimitiveOutsideIsland = {
         const name = primitiveName(node, b);
         if (!name) return;
         const ancestors = ancestorsOf(context, node);
-        const fns = ancestors.filter((a) => FN_TYPES.has(a.type));
-        if (fns.length === 0) {
+        if (enclosingFunctions(ancestors).length === 0) {
           context.report({ node, messageId: "outside", data: { name } });
-          return;
         }
-        const enclosing = fns[fns.length - 1];
-        const idx = ancestors.indexOf(enclosing);
-        const parent = idx > 0 ? ancestors[idx - 1] : parentOf(context, enclosing);
-        if (isComponentFn(enclosing, parent, ancestors.slice(0, idx), b)) return;
-        context.report({ node, messageId: "outside", data: { name } });
       },
     };
   },
 };
 
-const preferPlainHandler = {
+const noInstructionOutsideGenerator = {
   meta: {
-    type: "suggestion",
-    docs: { description: "Use a plain function unless action status or cancellation is used" },
+    type: "problem",
+    docs: { description: "Use when/watch/wait only inside a generator, with yield*" },
     messages: {
-      unused:
-        "action() is unused as a status object. Use a plain function unless you read .pending, .data, or .error.",
+      notGenerator:
+        "{{name}}() returns an instruction that only a generator frame can run. Make the enclosing component a generator and yield* it.",
+      notYielded: "Call yield* with {{name}}() — calling it directly discards the instruction.",
     },
     schema: [],
   },
   create(context) {
     const b = bindings();
-    const found = new Map();
     return {
       ImportDeclaration(node) {
         takeImport(b, node);
       },
-      VariableDeclarator(node) {
-        if (node.id.type !== "Identifier" || !node.init) return;
-        if (primitiveName(node.init, b) !== "action") return;
-        found.set(node.id.name, { node: node.init, used: false });
-      },
-      MemberExpression(node) {
-        if (node.computed || node.object.type !== "Identifier") return;
-        if (node.property.type !== "Identifier" || !ACTION_STATUS.has(node.property.name)) return;
-        const rec = found.get(node.object.name);
-        if (rec) rec.used = true;
-      },
-      "Program:exit"() {
-        for (const rec of found.values()) {
-          if (!rec.used) context.report({ node: rec.node, messageId: "unused" });
+      CallExpression(node) {
+        const name = primitiveName(node, b);
+        if (!name || !INSTRUCTIONS.has(name)) return;
+        // yield* wraps the CallExpression in a YieldExpression.
+        const parent = ancestorsOf(context, node).at(-1);
+        if (parent?.type === "YieldExpression") return;
+        const ancestors = ancestorsOf(context, node);
+        const fns = enclosingFunctions(ancestors);
+        const gen = fns.findLast((f) => f.generator === true);
+        if (!gen) {
+          context.report({ node, messageId: "notGenerator", data: { name } });
+          return;
+        }
+        // Inside a generator body but not under a yield — the nearest function
+        // between the call and the generator must not be a plain callback that
+        // escapes the frame. If the call sits directly in the generator, require yield*.
+        const genIdx = ancestors.indexOf(gen);
+        const between = ancestors.slice(genIdx + 1).filter((a) => FN_TYPES.has(a.type));
+        if (between.length === 0) {
+          context.report({ node, messageId: "notYielded", data: { name } });
         }
       },
     };
@@ -277,103 +167,37 @@ const preferLowercaseEvents = {
         context.report({
           node,
           messageId: "camel",
-          data: { name, suggested: "on" + name.slice(2).toLowerCase() },
+          data: { name, suggested: `on${name.slice(2).toLowerCase()}` },
         });
       }
     }
     return {
       JSXAttribute(node) {
-        const parent = parentOf(context, node);
-        const tag = parent && parent.name;
-        if (tag && tag.type === "JSXIdentifier" && PASCAL_CASE.test(tag.name)) return;
         if (node.name.type === "JSXIdentifier") checkName(node.name, node.name.name);
         if (node.name.type === "JSXNamespacedName") {
           checkName(node.name.namespace, node.name.namespace.name);
         }
       },
-      TaggedTemplateExpression(node) {
-        if (node.tag.type !== "Identifier" || node.tag.name !== "html") return;
-        for (const q of node.quasi.quasis) {
-          const text = q.value.cooked ?? q.value.raw;
-          const re = /\bon[A-Z][A-Za-z]*/g;
-          let m;
-          while ((m = re.exec(text))) checkName(node, m[0]);
-        }
-      },
-    };
-  },
-};
-
-const noDirectIslandCall = {
-  meta: {
-    type: "problem",
-    docs: { description: "Only call islands as children inside another island render" },
-    messages: {
-      direct:
-        "Do not call {{name}}() here. Nest it inside another island, or use {{name}}.toString / toStringAsync / hydratable.",
-    },
-    schema: [],
-  },
-  create(context) {
-    const b = bindings();
-    const { names, VariableDeclarator } = collectIslands(b);
-    return {
-      ImportDeclaration(node) {
-        takeImport(b, node);
-      },
-      VariableDeclarator,
-      CallExpression(node) {
-        const name = islandCallee(names, node.callee);
-        if (!name) return;
-        if (isInsideComponent(context, node, b)) return;
-        context.report({ node, messageId: "direct", data: { name } });
-      },
-    };
-  },
-};
-
-const requireSsrApi = {
-  meta: {
-    type: "problem",
-    docs: { description: "Use Island.toString / toStringAsync / hydratable for SSR" },
-    messages: {
-      awaitCall:
-        "Do not await {{name}}(). Use await {{name}}.toStringAsync() or await {{name}}.hydratable().",
-    },
-    schema: [],
-  },
-  create(context) {
-    const b = bindings();
-    const { names, VariableDeclarator } = collectIslands(b);
-    return {
-      ImportDeclaration(node) {
-        takeImport(b, node);
-      },
-      VariableDeclarator,
-      AwaitExpression(node) {
-        const arg = node.argument;
-        if (arg.type !== "CallExpression") return;
-        const name = islandCallee(names, arg.callee);
-        if (name) context.report({ node, messageId: "awaitCall", data: { name } });
-      },
+      "Property[value.type=/Function(Expression|Declaration)$/], Property[value.type='ArrowFunctionExpression']"() {},
     };
   },
 };
 
-const functionInState = {
+const functionInAtom = {
   meta: {
     type: "problem",
-    docs: { description: "Do not pass a function value to state() or a state setter" },
+    docs: { description: "atom(fn) is a computed initializer — wrap function values" },
     messages: {
-      init: "state({{name}}) treats the function as a lazy initializer. Wrap it: state(() => {{name}}).",
-      set: "{{setter}}({{name}}) runs as an updater. Store a function with {{setter}}(() => {{name}}).",
+      init: "atom({{name}}) treats the function as a computed initializer. Wrap it: atom(() => {{name}}).",
+      set: "{{setter}}({{name}}) is fine as a value, but computed atoms reject set(). Store a function with a plain wrapper if you really mean it.",
     },
     schema: [],
   },
   create(context) {
     const b = bindings();
     const fns = new Set();
-    const states = new Set();
+    const atoms = new Set();
+    const computed = new Set();
     return {
       ImportDeclaration(node) {
         takeImport(b, node);
@@ -390,23 +214,24 @@ const functionInState = {
         ) {
           fns.add(node.id.name);
         }
-        if (init && primitiveName(init, b) === "state") states.add(node.id.name);
+        if (!init || primitiveName(init, b) !== "atom") return;
+        atoms.add(node.id.name);
+        // atom(() => …) or atom(function…) — computed; flag set() on it.
+        if (init.arguments[0] && FN_TYPES.has(init.arguments[0].type)) computed.add(node.id.name);
       },
       CallExpression(node) {
         if (node.arguments.length === 0) return;
         const arg = node.arguments[0];
         if (arg.type !== "Identifier" || !fns.has(arg.name)) return;
-        if (primitiveName(node, b) === "state") {
+        if (primitiveName(node, b) === "atom") {
           context.report({ node: arg, messageId: "init", data: { name: arg.name } });
           return;
         }
         const setter = calleeName(node.callee);
-        if (setter && states.has(setter)) {
-          context.report({
-            node: arg,
-            messageId: "set",
-            data: { setter, name: arg.name },
-          });
+        // set(fn) on a computed atom never makes sense; on a writable atom it
+        // is the classic "I meant to store this function" mistake.
+        if (setter && atoms.has(setter) && computed.has(setter)) {
+          context.report({ node: arg, messageId: "set", data: { setter, name: arg.name } });
         }
       },
     };
@@ -416,13 +241,10 @@ const functionInState = {
 module.exports = {
   meta: { name: "oxlint-plugin-ilha" },
   rules: {
-    "pascal-case": pascalCase,
     "no-conditional-primitive": noConditionalPrimitive,
-    "no-primitive-outside-island": noPrimitiveOutsideIsland,
-    "prefer-plain-handler": preferPlainHandler,
+    "no-primitive-outside-component": noPrimitiveOutsideComponent,
+    "no-instruction-outside-generator": noInstructionOutsideGenerator,
     "prefer-lowercase-events": preferLowercaseEvents,
-    "no-direct-island-call": noDirectIslandCall,
-    "require-ssr-api": requireSsrApi,
-    "function-in-state": functionInState,
+    "function-in-atom": functionInAtom,
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilha/router",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "description": "A tiny SPA router for Ilha",
   "keywords": [
     "frontend",
@@ -31,6 +31,7 @@
   ],
   "type": "module",
   "sideEffects": false,
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
   "browser": {
     "process": false
@@ -41,10 +42,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
     "./server-island": {
       "types": "./dist/server-island.d.ts",
       "import": "./dist/server-island.js"
@@ -72,13 +69,14 @@
     "test": "bun test"
   },
   "dependencies": {
+    "effect": "^4.0.0-rc.112",
     "unplugin": "3.3.0"
   },
   "devDependencies": {
-    "ilha": "0.13.0",
+    "ilha": "0.14.0",
     "vite": "^8.2.2"
   },
   "peerDependencies": {
-    "ilha": ">=0.13.0"
+    "ilha": ">=0.14.0"
   }
 }

package/dist/server.d.ts

@@ -1,8 +0,0 @@
-import "ilha";
-import { type ServerAction } from "ilha/internal";
-/**
- * Declare an Oxide RPC action that can also be passed directly to server-island
- * event props or bound to a serializable payload with `.with()`.
- */
-export declare function action<A extends unknown[], R>(fn: (...args: A) => R): ServerAction<A, R>;
-export type { ServerAction } from "ilha/internal";

package/dist/server.js

@@ -1,14 +0,0 @@
-import "ilha";
-import { bindServerAction } from "ilha/internal";
-
-//#region src/server.ts
-/**
-* Declare an Oxide RPC action that can also be passed directly to server-island
-* event props or bound to a serializable payload with `.with()`.
-*/
-function action(fn) {
-	return bindServerAction(fn);
-}
-
-//#endregion
-export { action };