fratmscript 0.0.0-stage → 0.10.2

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# fratmscript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [FratmScript](https://github.com/kkratterf/fratmscript) compiler as an npm package: the real Rust compiler built to WebAssembly, a small JS API and a Vite plugin.
+
+```bash
+npm i fratmscript
+```
+
+## Compile from Node
+
+```js
+import { compile, format } from 'fratmscript';
+
+const { code, map, errors } = compile('stamm a dì("Uè!")', { filename: 'main.fratm' });
+// code   → 'console.log("Uè!");\n'
+// map    → source map v3 object (pass { sourceMap: false } to skip it)
+// errors → [] or [{ message, line, column, suggestion }], messages in Neapolitan
+
+format('si (overo) {\nstamm a dì(1)\n}').code; // same output as `fratm fmt`
+```
+
+`compile` never throws on invalid source: check `errors`.
+
+Errors thrown by the compiled code can be shown in Neapolitan too:
+
+```js
+import { runtimeError } from 'fratmscript';
+
+try {
+  run(code);
+} catch (e) {
+  console.error(runtimeError(e));
+  // 'nonEsiste' nun esiste: nun l'hê maje dichiarato cu 'chist è' o 'tien' (ReferenceError: nonEsiste is not defined)
+}
+```
+
+## Vite plugin
+
+```js
+// vite.config.js
+import fratmscript from 'fratmscript/vite';
+
+export default {
+  plugins: [fratmscript()],
+};
+```
+
+Then import `.fratm` files from your code, and from each other with `chiamm { … } da "./file.fratm"`:
+
+```js
+import { saluta } from './saluto.fratm';
+```
+
+Compile errors show up in the Vite overlay with their line and column, and source maps point at the `.fratm` files. The plugin has no dependency on Vite, so it also works as a Rollup plugin.
+
+For React Fast Refresh on `.fratm` components, add `@vitejs/plugin-react` after it and let it see the compiled files:
+
+```js
+import react from '@vitejs/plugin-react';
+
+export default {
+  plugins: [fratmscript(), react({ include: /\.(fratm|[jt]sx?)$/ })],
+};
+```
+
+### An API on the dev server
+
+`api` mounts a server written in FratmScript on the Vite dev server, so one `npm run dev` serves both the app and its API. The module's default export must have a `fetch(request)` method that returns a `Response`, as a [Hono](https://hono.dev) app does. It answers the requests under `/api`, and it is reloaded when you edit it.
+
+```js
+export default {
+  plugins: [fratmscript({ api: 'server/api.fratm' })],
+  // or fratmscript({ api: { entry: 'server/api.fratm', prefix: '/dati' } })
+};
+```
+
+```fratm
+// server/api.fratm
+chiamm { Hono } da "hono"
+chist è api = nu bell Hono().basePath("/api")
+api.get("/pizze", (c) => c.json(["Margherita", "Marinara"]))
+mann for predefinit api
+```
+
+In production run the same module with `node --import fratmscript/node` and a Node adapter such as `@hono/node-server`. `fratm nuovo --completa` sets all of this up.
+
+## Run .fratm files in Node
+
+```bash
+node --import fratmscript/node server.fratm
+```
+
+`fratmscript/node` registers a module hook (Node 20.6 or later) that compiles every `.fratm` file when it is loaded, so `.fratm` modules can import each other, npm packages and `node:` modules. Stack traces point at the `.fratm` lines, and compile errors are printed in Neapolitan with file, line and column.
+
+## In a web page, with a script tag
+
+No build step: load `browser.js` and write FratmScript in `<script type="text/fratmscript">` tags, inline or with `src`. They run in document order once the page has loaded; compile errors and uncaught runtime errors are printed in Neapolitan in the console, and dev tools show the `.fratm` source.
+
+```html
+<meta charset="utf-8">
+<script type="module" src="https://cdn.jsdelivr.net/npm/fratmscript/browser.js"></script>
+
+<script type="text/fratmscript">
+  chist è nome = "Gennaro"
+  stamm a dì(`Uè ${nome}!`)
+</script>
+<script type="text/fratmscript" src="pizzeria.fratm"></script>
+```
+
+`import { ready } from 'fratmscript/browser'` gives a promise that resolves when every script has run. Code that uses `chiamm`/`mann for` runs as a module.
+
+## In the browser, from JavaScript
+
+```js
+import { init, compile } from 'fratmscript/web';
+
+await init(); // fetches the .wasm file next to the module
+compile('tien x = 1').code;
+```

package/browser.d.ts

@@ -0,0 +1,2 @@
+/** Resolves with the number of `<script type="text/fratmscript">` tags that ran. */
+export const ready: Promise<number>;

package/browser.js

@@ -0,0 +1,44 @@
+// Runs <script type="text/fratmscript"> tags in a web page:
+//
+//   <script type="module" src="https://cdn.jsdelivr.net/npm/fratmscript/browser.js"></script>
+//   <script type="text/fratmscript">
+//     stamm a dì("Uè!")
+//   </script>
+//
+// Scripts run in document order once the page has loaded, inline or with
+// src="file.fratm". Compile errors and uncaught runtime errors are printed in
+// Neapolitan in the console. `ready` resolves when every script has run.
+import { init, compile, runtimeError } from './web.js';
+import { runScripts } from './lib/scripts.js';
+
+function execute(code, original, isModule) {
+  const script = document.createElement('script');
+  if (isModule) script.type = 'module';
+  script.textContent = code;
+  // Insert next to the original tag and drop it again: the code has run
+  // (classic scripts run synchronously when inserted).
+  original.after(script);
+  script.remove();
+}
+
+async function load(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+  return response.text();
+}
+
+function domReady() {
+  if (document.readyState !== 'loading') return Promise.resolve();
+  return new Promise((resolve) => document.addEventListener('DOMContentLoaded', resolve, { once: true }));
+}
+
+window.addEventListener('error', (event) => {
+  if (event.error instanceof Error) console.error(`🤌 ${runtimeError(event.error)}`);
+});
+window.addEventListener('unhandledrejection', (event) => {
+  if (event.reason instanceof Error) console.error(`🤌 ${runtimeError(event.reason)}`);
+});
+
+export const ready = Promise.all([init(), domReady()]).then(() =>
+  runScripts({ document, load, compile, execute, report: (message) => console.error(message) }),
+);

package/index.d.ts

@@ -0,0 +1,57 @@
+export interface CompileOptions {
+  /** Generate a source map (default: true). */
+  sourceMap?: boolean;
+  /** Name of the source file, used in the source map (default: "input.fratm"). */
+  filename?: string;
+  /**
+   * Library whose JSX runtime compiles JSX, as in `<source>/jsx-runtime` (default: "react").
+   * A `// @jsxImportSource preact` comment in the file wins over this option.
+   */
+  jsxImportSource?: string;
+}
+
+export interface FratmError {
+  /** Error message, in Neapolitan */
+  message: string;
+  /** 1-based line, when known */
+  line: number | null;
+  /** 1-based column, when known */
+  column: number | null;
+  /** A hint on how to fix it, when there is one */
+  suggestion: string | null;
+}
+
+export interface SourceMapV3 {
+  version: number;
+  file?: string;
+  sources: string[];
+  sourcesContent?: (string | null)[];
+  names: string[];
+  mappings: string;
+}
+
+export interface CompileResult {
+  /** Generated JavaScript, or null when there are errors */
+  code: string | null;
+  map: SourceMapV3 | null;
+  errors: FratmError[];
+}
+
+export interface FormatResult {
+  /** Formatted source, or null when the source does not compile */
+  code: string | null;
+  errors: FratmError[];
+}
+
+/** Compiles FratmScript source to JavaScript. Never throws on invalid source. */
+export function compile(source: string, options?: CompileOptions): CompileResult;
+/** Formats FratmScript source, like `fratm fmt`. */
+export function format(source: string): FormatResult;
+/** Version of the compiler. */
+export function version(): string;
+/**
+ * A JavaScript error thrown by compiled code, in Neapolitan, with the
+ * original message in brackets. Errors the program throws itself keep
+ * their message.
+ */
+export function runtimeError(error: unknown): string;

package/index.js

@@ -0,0 +1,7 @@
+// FratmScript compiler for Node.js (and bundlers that run in Node).
+import { createRequire } from 'node:module';
+import { createApi } from './lib/api.js';
+
+const wasm = createRequire(import.meta.url)('./wasm/node/fratm_wasm.js');
+
+export const { compile, format, version, runtimeError } = createApi(wasm);

package/lib/api.js

@@ -0,0 +1,51 @@
+// Turns the raw responses of the WASM bindings into the public API.
+
+/** @param {any} response */
+function toErrors(response) {
+  if (response.success) return [];
+  return [
+    {
+      message: response.error,
+      line: response.line ?? null,
+      column: response.column ?? null,
+      suggestion: response.suggestion ?? null,
+    },
+  ];
+}
+
+/** @param {any} wasm */
+export function createApi(wasm) {
+  function compile(source, options = {}) {
+    const { sourceMap = true, filename = 'input.fratm', jsxImportSource } = options;
+    const response = wasm.compile(String(source), sourceMap, jsxImportSource ?? undefined);
+    if (!response.success) {
+      return { code: null, map: null, errors: toErrors(response) };
+    }
+    let map = null;
+    if (response.sourceMap) {
+      map = JSON.parse(response.sourceMap);
+      map.sources = [filename];
+      map.file = filename.replace(/\.fratm$/, '') + '.js';
+    }
+    return { code: response.code, map, errors: [] };
+  }
+
+  function format(source) {
+    const response = wasm.format(String(source));
+    return response.success
+      ? { code: response.code, errors: [] }
+      : { code: null, errors: toErrors(response) };
+  }
+
+  function version() {
+    return wasm.version();
+  }
+
+  function runtimeError(error) {
+    const name = error && error.name ? String(error.name) : 'Error';
+    const message = error && error.message !== undefined ? String(error.message) : String(error);
+    return wasm.runtimeError(name, message);
+  }
+
+  return { compile, format, version, runtimeError };
+}

package/lib/fetch-middleware.js

@@ -0,0 +1,36 @@
+// Serves a fetch-style app (`app.fetch(request) => response`, as Hono and
+// other Web-standard servers have) from a Node or Connect middleware.
+
+/** The Web `Request` for a Node `IncomingMessage`. */
+export async function toRequest(req) {
+  const url = new URL(req.originalUrl ?? req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    for (const item of Array.isArray(value) ? value : [value]) headers.append(name, item);
+  }
+  const init = { method: req.method, headers };
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    init.body = Buffer.concat(chunks);
+  }
+  return new Request(url, init);
+}
+
+/** Writes a Web `Response` to a Node `ServerResponse`. */
+export async function sendResponse(res, response) {
+  res.statusCode = response.status;
+  for (const [name, value] of response.headers) {
+    if (name !== 'set-cookie') res.setHeader(name, value);
+  }
+  const cookies = response.headers.getSetCookie?.() ?? [];
+  if (cookies.length > 0) res.setHeader('set-cookie', cookies);
+  res.end(Buffer.from(await response.arrayBuffer()));
+}
+
+/** Whether `url` is `prefix` or below it: `/api` matches `/api/pizze`, not `/apiario`. */
+export function underPrefix(url, prefix) {
+  const path = (url ?? '/').split(/[?#]/, 1)[0];
+  return path === prefix || path.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`);
+}

package/lib/node-hooks.js

@@ -0,0 +1,32 @@
+// Module hooks registered by `fratmscript/node`. They run on Node's loader
+// thread and compile every .fratm file before it is evaluated.
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { compile } from '../index.js';
+import { formatError } from './scripts.js';
+
+const FRATM = /\.fratm$/;
+
+export async function load(url, context, nextLoad) {
+  if (!FRATM.test(url.split(/[?#]/, 1)[0])) return nextLoad(url, context);
+
+  const path = fileURLToPath(url);
+  const source = await readFile(path, 'utf8');
+  const result = compile(source, { filename: path });
+  if (result.errors.length > 0) {
+    const [first] = result.errors;
+    const error = new SyntaxError(formatError(path, first));
+    // Replace the loader's own frames with the .fratm position (a stack with
+    // no frame at all would be printed in brackets)
+    error.stack = `${error.name}: ${error.message}\n    at ${path}:${first.line ?? 1}:${first.column ?? 1}`;
+    throw error;
+  }
+
+  let code = result.code;
+  if (result.map) {
+    result.map.sources = [url];
+    const map = Buffer.from(JSON.stringify(result.map)).toString('base64');
+    code += `\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${map}\n`;
+  }
+  return { format: 'module', source: code, shortCircuit: true };
+}

package/lib/scripts.js

@@ -0,0 +1,75 @@
+// Finds <script type="text/fratmscript"> tags, compiles them and runs the
+// JavaScript, in document order. Kept free of globals so it can be tested
+// in Node with a fake document (see test/browser.test.js).
+
+export const SCRIPT_TYPE = 'text/fratmscript';
+
+/**
+ * @param {object} env
+ * @param {Document} env.document
+ * @param {(url: string) => Promise<string>} env.load       fetches a `src=` script
+ * @param {(source: string, options: object) => any} env.compile  the fratmscript compile()
+ * @param {(code: string, script: Element, isModule: boolean) => void} env.execute  runs compiled JS
+ * @param {(message: string) => void} env.report             prints a compile error
+ * @returns {Promise<number>} how many scripts ran
+ */
+export async function runScripts({ document, load, compile, execute, report }) {
+  const scripts = Array.from(document.querySelectorAll(`script[type="${SCRIPT_TYPE}"]`));
+  // Fetch every external script up front, then run them in order
+  const sources = scripts.map((script) => {
+    const src = script.getAttribute('src');
+    return src ? load(new URL(src, document.baseURI).href) : Promise.resolve(script.textContent ?? '');
+  });
+
+  let ran = 0;
+  for (let i = 0; i < scripts.length; i++) {
+    const script = scripts[i];
+    const name = scriptName(script, i);
+    let source;
+    try {
+      source = await sources[i];
+    } catch (error) {
+      report(`FratmScript: nun riesco a caricà ${name} (${error && error.message ? error.message : error})`);
+      continue;
+    }
+    const result = compile(source, { filename: name });
+    if (result.errors.length > 0) {
+      for (const error of result.errors) report(formatError(name, error));
+      continue;
+    }
+    let code = result.code;
+    if (result.map) {
+      code += `\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64(JSON.stringify(result.map))}`;
+    }
+    code += `\n//# sourceURL=${name}`;
+    execute(code, script, isModule(result.code));
+    ran++;
+  }
+  return ran;
+}
+
+/** File name shown in errors and dev tools: the `src`, or `fratmscript-N.fratm`. */
+export function scriptName(script, index) {
+  const src = script.getAttribute('src');
+  if (src) return src.split(/[?#]/)[0].split('/').pop() || src;
+  return `fratmscript-${index + 1}.fratm`;
+}
+
+export function formatError(name, error) {
+  const where = error.line ? `${name}:${error.line}:${error.column ?? 1}` : name;
+  // The message already starts with "Riga X, colonna Y: "; the location is in `where`
+  const message = String(error.message).replace(/^Riga \d+, colonna \d+: /, '');
+  return `FratmScript ${where}: ${message}${error.suggestion ? `\n${error.suggestion}` : ''}`;
+}
+
+/** Compiled code that imports or exports has to run as a module. */
+export function isModule(code) {
+  return /^(import|export)\b/m.test(code);
+}
+
+function base64(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}

package/node.d.ts

@@ -0,0 +1,3 @@
+// `import 'fratmscript/node'` (or `node --import fratmscript/node`) only
+// registers the .fratm loader; it exports nothing.
+export {};

package/node.js

@@ -0,0 +1,7 @@
+// Lets Node.js run .fratm files: `node --import fratmscript/node main.fratm`.
+// Registers module hooks that compile each .fratm file when it is loaded.
+import { register } from 'node:module';
+
+register('./lib/node-hooks.js', import.meta.url);
+// Stack traces point at the .fratm lines through the inline source maps
+process.setSourceMapsEnabled(true);

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "fratmscript",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.2",
+  "description": "FratmScript compiler (WebAssembly) and Vite plugin: JavaScript, ma comme si deve 🤌",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkratterf/fratmscript.git",
+    "directory": "packages/fratmscript"
+  },
+  "homepage": "https://github.com/kkratterf/fratmscript/tree/main/packages/fratmscript#readme",
+  "keywords": [
+    "fratmscript",
+    "napoletano",
+    "compiler",
+    "transpiler",
+    "wasm",
+    "vite-plugin"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./vite": {
+      "types": "./vite.d.ts",
+      "default": "./vite.js"
+    },
+    "./node": {
+      "types": "./node.d.ts",
+      "default": "./node.js"
+    },
+    "./web": {
+      "types": "./web.d.ts",
+      "default": "./web.js"
+    },
+    "./browser": {
+      "types": "./browser.d.ts",
+      "default": "./browser.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "vite.js",
+    "vite.d.ts",
+    "node.js",
+    "node.d.ts",
+    "web.js",
+    "web.d.ts",
+    "browser.js",
+    "browser.d.ts",
+    "lib/",
+    "wasm/node/package.json",
+    "wasm/node/fratm_wasm.js",
+    "wasm/node/fratm_wasm_bg.wasm",
+    "wasm/web/fratm_wasm.js",
+    "wasm/web/fratm_wasm_bg.wasm"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build-wasm.js",
+    "test": "node --test test/*.test.js"
+  }
+}

package/vite.d.ts

@@ -0,0 +1,27 @@
+export interface FratmPluginOptions {
+  /** Emit source maps for compiled files (default: true). */
+  sourceMap?: boolean;
+  /** Library whose JSX runtime compiles JSX in `.fratm` files (default: "react"). */
+  jsxImportSource?: string;
+  /**
+   * Serve an API from the dev server: a module (e.g. "server/api.fratm") whose
+   * default export has `fetch(request)`, such as a Hono app. It answers the
+   * requests under `prefix` (default "/api").
+   */
+  api?: string | { entry: string; prefix?: string };
+}
+
+/** A Vite/Rollup plugin; typed loosely so it does not depend on vite's types. */
+export interface FratmPlugin {
+  name: string;
+  enforce: 'pre';
+  configureServer(server: {
+    middlewares: { use(fn: (req: any, res: any, next: (error?: unknown) => void) => void): void };
+    ssrLoadModule(url: string): Promise<Record<string, any>>;
+    ssrFixStacktrace?(error: Error): void;
+  }): void;
+  transform(this: unknown, source: string, id: string): { code: string; map: unknown } | null;
+}
+
+export default function fratmscript(options?: FratmPluginOptions): FratmPlugin;
+export { fratmscript };

package/vite.js

@@ -0,0 +1,64 @@
+// Vite (and Rollup) plugin that compiles imported `.fratm` files.
+import { compile } from './index.js';
+import { sendResponse, toRequest, underPrefix } from './lib/fetch-middleware.js';
+
+const FRATM = /\.fratm$/;
+// A request for a .fratm file that Vite would serve as it is
+const RAW_FRATM_REQUEST = /^[^?#]*\.fratm(?:$|[?#])/;
+
+export default function fratmscript(options = {}) {
+  const { sourceMap = true, jsxImportSource } = options;
+  // `api: "server/api.fratm"` or `{ entry, prefix }`: a module whose default
+  // export has `fetch(request)` (a Hono app) answers the requests under prefix
+  const api = typeof options.api === 'string' ? { entry: options.api } : options.api;
+  const apiPrefix = api?.prefix ?? '/api';
+  // Vite resolves "/server/api.fratm" from the project root; "server/…" would be a package
+  const apiEntry = api && (/^[./]/.test(api.entry) ? api.entry : `/${api.entry}`);
+  return {
+    name: 'fratmscript',
+    enforce: 'pre',
+    configureServer(server) {
+      // The dev server only compiles requests it knows are modules. Imports
+      // between modules get `?import` from Vite, but the `<script src=…>`
+      // in index.html does not: add it, so the entry is compiled too.
+      server.middlewares.use((req, _res, next) => {
+        if (req.url && RAW_FRATM_REQUEST.test(req.url) && !/[?&]import(?:[=&#]|$)/.test(req.url)) {
+          req.url += req.url.includes('?') ? '&import' : '?import';
+        }
+        next();
+      });
+      if (!api) return;
+      server.middlewares.use(async (req, res, next) => {
+        if (!underPrefix(req.url, apiPrefix)) return next();
+        try {
+          // Loaded on each request: Vite reloads it when a server file changes
+          const module = await server.ssrLoadModule(apiEntry);
+          const app = module.default;
+          if (typeof app?.fetch !== 'function') {
+            throw new Error(`${api.entry} adda mannà for predefinit n'app cu fetch(), tipo nu bell Hono()`);
+          }
+          await sendResponse(res, await app.fetch(await toRequest(req)));
+        } catch (error) {
+          server.ssrFixStacktrace?.(error);
+          next(error);
+        }
+      });
+    },
+    transform(source, id) {
+      const file = id.split('?', 1)[0];
+      if (!FRATM.test(file)) return null;
+      const result = compile(source, { sourceMap, filename: file, jsxImportSource });
+      if (result.errors.length > 0) {
+        const [error] = result.errors;
+        this.error({
+          message: error.suggestion ? `${error.message}\n${error.suggestion}` : error.message,
+          id: file,
+          loc: error.line == null ? undefined : { file, line: error.line, column: (error.column ?? 1) - 1 },
+        });
+      }
+      return { code: result.code, map: result.map };
+    },
+  };
+}
+
+export { fratmscript };