npm - azoxjs - Versions diffs - 0.1.0 → 0.2.0 - Mend

azoxjs 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +112 -5
package/core/build.js +237 -41
package/core/cli/router.js +28 -0
package/core/commands/create.js +44 -10
package/core/commands/dev.js +34 -19
package/core/commands/doctor.js +6 -1
package/core/compiler/compileToJs.js +506 -36
package/core/compiler/html.js +28 -0
package/core/compiler/parser.js +204 -9
package/core/compiler/resolveComponents.js +212 -39
package/core/compiler/sourceResolver.js +42 -0
package/core/nodeResolver.js +15 -0
package/core/reactivity/signal.js +36 -1
package/core/renderer/moduleBindings.js +88 -0
package/core/renderer/renderToHtml.js +94 -18
package/core/renderer/serverScope.js +83 -0
package/core/router/navigate.js +211 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,6 +1,8 @@
 # Azox Framework
 [![CI](https://github.com/darilpratomo/azox/actions/workflows/ci.yml/badge.svg)](https://github.com/darilpratomo/azox/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/azoxjs.svg)](https://www.npmjs.com/package/azoxjs)
+[![install size](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/azoxjs)
 **The Sound of Future Web**
@@ -9,7 +11,7 @@ third-party CLI dependencies, no borrowed syntax from React, Vue, or
 Next.js. It compiles `.azox` components directly into fine-grained,
 signal-driven DOM updates.
-> Status: early development (v0.1.0). APIs are unstable and will
+> Status: early development (v0.2.0). APIs are unstable and will
 > change without notice until v1.0.
 ## Why Azox
@@ -120,10 +122,114 @@ Declaring props with `props()` is what lets the compiler reject a
 caller that passes something the component never asked for, instead
 of dropping it silently.
-In this version components are presentational: they take props and
-render markup, and state lives in the page that uses them. A
-component that declares its own logic is rejected with an explicit
-error rather than quietly sharing the caller's scope.
+A component may hold its own state. Its `<script>` becomes a scope
+of its own, so two uses of the same component are independent — each
+`<Counter />` below counts separately:
+```html
+<!-- components/Counter.azox -->
+<script>
+  import { signal } from 'azox/reactivity';
+  const count = signal(0);
+</script>
+<button on:click={() => count.set(count() + 1)}>{count()}</button>
+```
+```html
+<main>
+  <Counter />
+  <Counter />
+</main>
+```
+There is still no component instance at runtime: the compiler wraps
+each use in its own JavaScript scope, which is ordinary scoping
+rather than a framework construct.
+## Loops and conditionals
+Control flow is expressed as tags, so it nests inside markup like
+anything else.
+```html
+<ul>
+  <each item={todos()} as="todo" index="i">
+    <li>{i + 1}. {todo}</li>
+  </each>
+</ul>
+<if cond={user()}>
+  <p>Signed in as {user().name}</p>
+<else />
+  <a href="/login">Sign in</a>
+</if>
+```
+Each block marks its place with a pair of comment nodes, and an
+update replaces only the nodes between them.
+By default a change to a list rebuilds its rows. Give a row an
+identity with `key` and it survives instead: reordering moves it,
+removing one leaves the rest untouched, and adding one does not
+disturb what is already there.
+```html
+<each item={tasks()} as="task" key={task.id}>
+  <li><TaskRow title={task.title} /></li>
+</each>
+```
+Use something stable and unique to the row — a database id, not its
+position, since a position changes when the list does.
+## Client-side routing
+By default every link is a full page load, which is the right
+behaviour for a static site. Opt in to client-side navigation with
+`router: true` in your project's `package.json`:
+```json
+{
+  "router": true
+}
+```
+Internal links are then swapped in place: the new page's HTML is
+fetched, the document body and `<head>` are replaced, and its module
+runs. Scroll position, the back button, and `<a target>` all behave
+as they would with a full load. A link is prefetched when the pointer
+enters it, so the page is usually already in hand by the time it is
+clicked.
+Anything the router cannot handle — an external origin, a download,
+a modifier-click — falls through to the browser untouched.
+## Importing data
+A `<script>` block may import a `.json` file, which is how a page
+reads a constant it should not have written out by hand:
+```html
+<script>
+  import pkg from '../package.json' with { type: 'json' };
+</script>
+<span>v{pkg.version}</span>
+```
+The file is read once during the build. Server rendering evaluates
+against it, and the value is compiled into the module as a constant
+rather than imported — the file sits outside the build directory and
+is never deployed, so an import would 404 in the browser.
+Only the properties the markup reads are included, so importing
+`package.json` for a version does not ship the rest of the file to
+every visitor.
+Importing a `.js` module is not supported: it would mean executing
+project code during the build. Use a `.json` file for data, and
+`azox/reactivity` for signals.
 ## Getting Started
@@ -179,6 +285,7 @@ azox/
 │   ├── dev/                  dev server, file watching, live reload
 │   ├── reactivity/           signal() / effect() / computed()
 │   ├── renderer/             server-side HTML rendering
+│   ├── router/               opt-in client-side navigation
 │   ├── build.js              the build pipeline, shared by commands
 │   ├── routes.js             file layout → urls and output paths
 │   └── meta.js               version and identity strings

package/core/build.js CHANGED Viewed

@@ -3,14 +3,27 @@
 // result. `azox compile` runs it once; `azox dev` runs it on every
 // change, so it returns data rather than printing.
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  copyFileSync,
+  existsSync,
+  readdirSync,
+  rmSync,
+} from 'node:fs';
+import { resolve, basename, relative, dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
 import { parseAzox } from './compiler/parser.js';
 import { resolveComponents } from './compiler/resolveComponents.js';
 import { compileToModule } from './compiler/compileToJs.js';
 import { renderToHtml } from './renderer/renderToHtml.js';
+import { parseImports } from './renderer/moduleBindings.js';
+import { evaluateScript } from './renderer/serverScope.js';
+import { escapeHtml } from './compiler/html.js';
 import { collectRoutes, findRoute } from './routes.js';
+import { createNodeResolver } from './nodeResolver.js';
 import { ROOT_DIR } from './meta.js';
 import { BuildError } from './buildError.js';
@@ -20,7 +33,15 @@ import { BuildError } from './buildError.js';
 // host can serve it with no install step.
 const RUNTIME_FILENAME = 'azox-runtime.js';
+// The client-side router is opt-in, via `router: true` in the project's
+// package.json. Changing how every link behaves is not something a
+// project should get without asking, and a site of plain documents is
+// perfectly well served by ordinary navigation.
+const ROUTER_FILENAME = 'azox-router.js';
 export const PAGES_DIR = 'pages';
+export const COMPONENTS_DIR = 'components';
+export const PUBLIC_DIR = 'public';
 export const BUILD_DIR = '.azox/build';
 export { BuildError };
@@ -37,12 +58,17 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   // Components are inlined here, before either output is produced, so
   // the compiler and the renderer both see plain markup.
-  const ast = resolveComponents(parsed, sourcePath);
+  const ast = resolveComponents(parsed, sourcePath, createNodeResolver());
+  // Imports the script pulls in are loaded once: server rendering
+  // evaluates against them, and the client module inlines them rather
+  // than importing a path that is never deployed.
+  const inlineModules = loadModules(ast.script, sourcePath, ast.componentImports ?? []);
   // SSR pass: render initial markup without touching browser DOM APIs.
   let html;
   try {
-    html = renderToHtml(ast, buildServerScope(ast.script));
+    html = renderToHtml(ast, buildServerScope(ast.script, inlineModules), inlineModules);
   } catch (error) {
     if (!(error instanceof BuildError)) throw error;
     throw new BuildError(`in ${PAGES_DIR}/${name}.azox: ${error.message}`);
@@ -62,9 +88,15 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   const clientModule = rewriteRuntimeImports(
     compileToModule(ast, {
-      sourcePath,
-      outPath: clientPath,
       runtimeSpecifier,
+      // The user's own relative imports were written next to the
+      // page; the compiled module lives in .azox/build/, so they need
+      // re-expressing from there.
+      // An import hoisted out of a component is relative to that
+      // component's file, which is why the hook takes a path.
+      rewriteImports: (script, from = sourcePath) =>
+        rebaseImports(script, dirname(from), clientPath),
+      inlineModules,
     }),
     runtimeSpecifier
   );
@@ -76,7 +108,14 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   const runtimePath = resolve(buildRoot, RUNTIME_FILENAME);
   copyFileSync(resolve(ROOT_DIR, 'core/reactivity/signal.js'), runtimePath);
-  let document = wrapDocument(html, projectTitle(projectDir));
+  const router = routerEnabled(projectDir);
+  if (router) {
+    copyFileSync(resolve(ROOT_DIR, 'core/router/navigate.js'), resolve(buildRoot, ROUTER_FILENAME));
+  }
+  let document = wrapDocument(html, projectTitle(projectDir), ast.head, {
+    routerSrc: router ? `${route.assetPrefix}${ROUTER_FILENAME}` : null,
+  });
   if (transformHtml) document = transformHtml(document);
   const htmlPath = resolve(buildRoot, route.htmlPath);
@@ -94,7 +133,86 @@ export function buildAll(projectDir, options) {
     );
   }
-  return routes.map((route) => buildRoute(projectDir, route, options));
+  const results = routes.map((route) => buildRoute(projectDir, route, options));
+  const assets = copyPublicAssets(projectDir);
+  removeStaleOutput(projectDir, results, assets);
+  return results;
+}
+// Deletes output belonging to pages that no longer exist. Without
+// this, deleting a page leaves its built copy behind and a deployed
+// site keeps serving it.
+//
+// Deliberately narrow: it only ever removes an index.html or a
+// page.client.js that this build did not just write, and only inside
+// the build directory. Anything else found there — a file copied from
+// public/, something a user put there — is left alone.
+function removeStaleOutput(projectDir, results, assets = []) {
+  const buildRoot = resolve(projectDir, BUILD_DIR);
+  if (!existsSync(buildRoot)) return;
+  const written = new Set([
+    ...results.flatMap((result) => [result.htmlPath, result.clientPath]),
+    ...assets,
+  ]);
+  const generated = new Set(['index.html', 'page.client.js']);
+  const emptied = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        // A directory left empty held only pages that are now gone.
+        if (readdirSync(full).length === 0) emptied.push(full);
+        continue;
+      }
+      if (generated.has(entry.name) && !written.has(full)) rmSync(full);
+    }
+  };
+  walk(buildRoot);
+  // Innermost first, so a nested route's directories go too.
+  for (const dir of emptied.reverse()) {
+    if (existsSync(dir) && readdirSync(dir).length === 0) rmSync(dir, { recursive: true });
+  }
+}
+// Everything in public/ is copied to the build root untouched, so a
+// stylesheet, font or image is referenced by the same path in source
+// and in the built site: public/style.css -> /style.css.
+export function copyPublicAssets(projectDir) {
+  const publicDir = resolve(projectDir, PUBLIC_DIR);
+  if (!existsSync(publicDir)) return [];
+  const buildRoot = resolve(projectDir, BUILD_DIR);
+  const copied = [];
+  const walk = (dir, relativeDir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const from = join(dir, entry.name);
+      const to = join(buildRoot, relativeDir, entry.name);
+      if (entry.isDirectory()) {
+        mkdirSync(to, { recursive: true });
+        walk(from, join(relativeDir, entry.name));
+      } else {
+        mkdirSync(dirname(to), { recursive: true });
+        copyFileSync(from, to);
+        copied.push(to);
+      }
+    }
+  };
+  walk(publicDir, '');
+  return copied;
 }
 // Builds a single page by route name or URL.
@@ -110,8 +228,31 @@ export function buildPage(projectDir, pageName, options) {
 // Rewrites the bare specifier a page's own <script> uses to the same
 // path the compiler emitted for the runtime import.
+//
+// Anchored to an import statement on its own line. Matching the bare
+// string anywhere would rewrite data that merely contains it — a JSON
+// import inlined into the module turned `"bin": {"azox": …}` into a
+// path to the runtime.
 function rewriteRuntimeImports(code, runtimeSpecifier) {
-  return code.replace(/(['"])azox(?:\/reactivity)?\1/g, `'${runtimeSpecifier}'`);
+  return code.replace(
+    /^([ \t]*import\s[\s\S]*?from\s+)(['"])azox(?:js)?(?:\/reactivity)?\2/gm,
+    `$1'${runtimeSpecifier}'`
+  );
+}
+// Re-expresses the relative imports in a page's <script> so they
+// still resolve from the compiled module's directory. Lives here
+// rather than in the compiler because it is a fact about where files
+// land on disk, which the compiler deliberately knows nothing about.
+function rebaseImports(script, sourceDir, outPath) {
+  return script.replace(
+    /(from\s+|import\s+)(['"])(\.[^'"]*)\2/g,
+    (full, keyword, quote, specifier) => {
+      let rebased = relative(dirname(outPath), resolve(sourceDir, specifier));
+      if (!rebased.startsWith('.')) rebased = `./${rebased}`;
+      return `${keyword}${quote}${rebased}${quote}`;
+    }
+  );
 }
 // A compiler must never write output it knows is broken. Parsing the
@@ -159,60 +300,115 @@ function projectTitle(projectDir) {
 // evaluate the expressions the template references. The script is
 // trusted project source, not user input — the same assumption any
 // template engine's SSR step makes.
-function buildServerScope(script) {
-  // Strip imports: the server supplies its own `signal` stub rather
-  // than loading the real reactive runtime.
-  const body = script.replace(/^\s*import\s.+?;\s*$/gm, '');
+function buildServerScope(script, modules = {}) {
+  // Strip imports: the server supplies its own primitives rather than
+  // loading the real reactive runtime, and anything else a script
+  // imports was resolved by loadModules and is passed in.
+  const body = script.replace(/^\s*import\s.+?;?\s*$/gm, '');
   try {
-    const fn = new Function('signal', `${body}\nreturn { ${declaredNames(body).join(', ')} };`);
-    return fn(serverSignal);
+    return evaluateScript(body, [], [], modules);
   } catch (error) {
+    if (error instanceof BuildError) throw error;
     throw new BuildError(`failed to evaluate the page's <script> block: ${error.message}`);
   }
 }
-// SSR needs only the current value, not reactivity, so `signal()` on
-// the server is a plain boxed value.
-function serverSignal(initial) {
-  let value = initial;
-  const read = () => value;
-  read.set = (next) => {
-    value = typeof next === 'function' ? next(value) : next;
-  };
-  read.peek = () => value;
-  return read;
-}
+// Resolves what a script's imports bring in, so server rendering sees
+// the same values the browser will.
+//
+// Only JSON is loaded. A JSON import is synchronous and has no side
+// effects, which suits a build step that must stay synchronous — and
+// it covers the case this exists for: reading a version or some other
+// constant out of package.json. Importing a .js module would mean
+// executing project code during the build, and `require(esm)` only
+// works from Node 22.12, below the floor this package declares.
+function loadModules(script, sourcePath, componentImports = []) {
+  // A component's hoisted import is relative to the component's own
+  // file, so each is resolved against the path it came with.
+  const imports = [
+    ...parseImports(script).map((entry) => ({ ...entry, from: sourcePath })),
+    ...componentImports.flatMap((entry) =>
+      parseImports(entry.statement).map((parsed) => ({ ...parsed, from: entry.path }))
+    ),
+  ];
+  if (!imports.length) return {};
+  const bindings = {};
+  for (const { specifier, bindings: names, from } of imports) {
+    if (!specifier.endsWith('.json')) {
+      throw new BuildError(
+        `cannot import '${specifier}': a <script> block may import .azox components, ` +
+          `'azox/reactivity', and .json files. Other modules are not available during ` +
+          `server rendering.`
+      );
+    }
+    const require = createRequire(from ? `file://${from}` : import.meta.url);
+    let loaded;
+    try {
+      loaded = require(specifier);
+    } catch (error) {
+      throw new BuildError(`cannot import '${specifier}': ${error.message.split('\n')[0]}`);
+    }
-function declaredNames(script) {
-  const names = [];
-  const regex = /const\s+(\w+)\s*=/g;
-  let match;
-  while ((match = regex.exec(script))) names.push(match[1]);
-  return names;
+    for (const { local, imported } of names) {
+      if (imported === '*' || imported === 'default') bindings[local] = loaded;
+      else bindings[local] = loaded[imported];
+    }
+  }
+  return bindings;
 }
 // The client module sits next to the page's index.html, so the src is
 // the same for every route regardless of how deep it is.
-function wrapDocument(bodyHtml, title) {
+// A page's own <head> block wins over the fallback title, so a page
+// can set its own <title>, stylesheets and meta tags.
+function wrapDocument(bodyHtml, title, head = '', { routerSrc = null } = {}) {
+  const hasOwnTitle = /<title>/i.test(head);
+  // The router is loaded after the page's own module, so a page is
+  // interactive before navigation is enhanced.
+  const router = routerSrc
+    ? `\n<script type="module">import { startRouter } from '${routerSrc}'; startRouter();</script>`
+    : '';
   return `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${escapeHtml(title)}</title>
-</head>
+${hasOwnTitle ? '' : `  <title>${escapeHtml(title)}</title>\n`}${head ? indent(head) + '\n' : ''}</head>
 <body>
 <div data-azox-root>${bodyHtml}</div>
-<script type="module" src="./page.client.js"></script>
+<script type="module" src="./page.client.js"></script>${router}
 </body>
 </html>
 `;
 }
-function escapeHtml(str) {
-  return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+// Reads `router` from the project's package.json. A malformed file is
+// not this function's problem to report — the build reads it again for
+// the page title and will surface anything wrong there.
+function routerEnabled(projectDir) {
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).router === true;
+  } catch {
+    return false;
+  }
+}
+function indent(block) {
+  return block
+    .split('\n')
+    .map((line) => (line.trim() ? `  ${line.trim()}` : line))
+    .join('\n');
 }

package/core/cli/router.js CHANGED Viewed

@@ -20,11 +20,13 @@ export const registry = {
     run: devCommand,
     describe: 'Serve the project and rebuild on every change',
     examples: ['azox dev', 'azox dev --port=5000'],
+    flags: ['port', 'host'],
   },
   compile: {
     run: compileCommand,
     describe: 'Compile pages to HTML + hydration modules',
     examples: ['azox compile', 'azox compile --page=about'],
+    flags: ['page'],
   },
   doctor: {
     run: doctorCommand,
@@ -65,9 +67,35 @@ export function runCommand(command, context) {
     return;
   }
+  const unknown = unknownFlags(context.flags, entry.flags ?? []);
+  if (unknown.length) {
+    const plural = unknown.length === 1 ? 'flag' : 'flags';
+    console.error(
+      `Azox: unknown ${plural} for "${resolved}": ${unknown.map((f) => `--${f}`).join(', ')}`
+    );
+    console.error(
+      entry.flags?.length
+        ? `It accepts: ${entry.flags.map((f) => `--${f}`).join(', ')}.`
+        : 'It accepts no flags.'
+    );
+    process.exitCode = 1;
+    return;
+  }
   return entry.run({ ...context, registry });
 }
+// A mistyped flag used to be ignored, so `azox compile --pge=about`
+// quietly built every page while looking as though it had built one.
+// Command-selecting flags are allowed everywhere, since they are how
+// the command was chosen in the first place.
+function unknownFlags(flags, accepted) {
+  const always = new Set([...Object.keys(FLAG_ALIASES), ...accepted]);
+  return Object.keys(flags).filter((flag) => !always.has(flag));
+}
 function aliasFor(flags) {
   for (const [flag, command] of Object.entries(FLAG_ALIASES)) {
     if (flags[flag]) return command;

package/core/commands/create.js CHANGED Viewed

@@ -88,18 +88,46 @@ function starterPage(name) {
   import Counter from '../components/Counter.azox';
   import { signal } from 'azox/reactivity';
-  const count = signal(0);
+  const tasks = signal([
+    { id: 1, title: 'Edit this page', done: true },
+    { id: 2, title: 'Add a page of your own', done: false },
+  ]);
+  const draft = signal('');
+  let nextId = 3;
 </script>
 <main class="page">
   <h1>${name}</h1>
   <p>Built with Azox.</p>
-  <Counter label="Clicks" value={count()} />
-  <button on:click={() => count.set(count() + 1)}>
-    Add one
-  </button>
+  <!-- Each Counter holds a count of its own. -->
+  <Counter label="Left" />
+  <Counter label="Right" />
+  <!-- key={task.id} gives each row an identity, so adding to the
+       list leaves the rows already there untouched. -->
+  <ul>
+    <each item={tasks()} as="task" index="i" key={task.id}>
+      <li>
+        <if cond={task.done}>
+          <s>{i + 1}. {task.title}</s>
+        <else />
+          <span>{i + 1}. {task.title}</span>
+        </if>
+      </li>
+    </each>
+  </ul>
+  <input
+    value={draft()}
+    on:input={(e) => draft.set(e.target.value)}
+    placeholder="Add a task"
+  />
+  <button on:click={() => {
+    if (!draft()) return;
+    tasks.set([...tasks(), { id: nextId++, title: draft(), done: false }]);
+    draft.set('');
+  }}>Add</button>
   <p><a href="/about">About</a></p>
 </main>
@@ -117,14 +145,20 @@ function aboutPage(name) {
 `;
 }
-// Components take props and render markup. State lives in the page
-// that uses them.
+// A component may hold state of its own, and each use gets its own
+// copy — the two Counters on the starter page count independently.
 function starterComponent() {
   return `<script>
-  const { label, value } = props();
+  import { signal } from 'azox/reactivity';
+  const { label } = props();
+  const count = signal(0);
 </script>
-<p class="counter">{label}: {value}</p>
+<span class="counter">
+  {label}: {count()}
+  <button on:click={() => count.set(count() + 1)}>+</button>
+</span>
 `;
 }