wawesome 0.0.14 → 0.0.15

package/README.md

@@ -215,6 +215,33 @@ Three headers arrive or leave on it, and the stripping is what makes them worth
 | `x-wawesome-invocation-id` | outbound | The id of this run — the key to fetch its logs with `npx wawesome logs --invocation <id>`. |
 | `x-wawesome-error` | outbound | Present only when the platform failed, never when your Function did. Its *absence* means the status on the wire is yours — up to the moment your response is committed, and no further. |
 
+### Testing against the guest's JavaScript surface
+
+Your Function does not run on Node. The engine has no `Intl`, and its `toLocaleString` ignores the
+locale you pass — `(1234.5).toLocaleString('en-US')` comes back as `"1234.5"`, not `"1,234.50"`. On
+Node both work, which is how a green suite ships a Function that throws in production, or renders
+markup the browser then refuses to hydrate.
+
+Point your test suite at the guest's surface instead:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { setupFiles: ["wawesome/vitest-setup"] },
+});
+```
+
+Templates scaffolded with `wawesome init --template` ship this already. With it in place `Intl` is
+gone, `MessageChannel` is the platform's own implementation rather than Node's, and the
+locale-sensitive methods throw with a message naming the remedy — they throw rather than return the
+engine's unlocalised answer because the platform declares them unsupported, and a wrong string that
+fails nowhere is the thing this is here to stop you shipping.
+
+If you bundle an `Intl` polyfill, declare it in your `package.json` as you normally would — a
+dependency that provides `Intl` is left in place rather than stripped out from under you.
+
 ### Local Development / Gateway Overrides
 
 If you are running a local gateway or self-hosted instance, you can configure your CLI Gateway URL using any of the

package/dist/guest-parity-CWuYJPbS.mjs

@@ -0,0 +1,272 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region ../../server/guest-surface/message-channel.js
+const ENTANGLED = Symbol("entangled");
+const QUEUE = Symbol("queue");
+const STARTED = Symbol("started");
+const CLOSED = Symbol("closed");
+const LISTENERS = Symbol("listeners");
+const ONMESSAGE = Symbol("onmessage");
+var MessagePort = class {
+	constructor() {
+		this[ENTANGLED] = null;
+		this[QUEUE] = [];
+		this[STARTED] = false;
+		this[CLOSED] = false;
+		this[LISTENERS] = [];
+		this[ONMESSAGE] = null;
+		this.onmessageerror = null;
+	}
+	get onmessage() {
+		return this[ONMESSAGE];
+	}
+	set onmessage(handler) {
+		this[ONMESSAGE] = handler;
+		if (handler) this.start();
+	}
+	start() {
+		if (this[STARTED]) return;
+		this[STARTED] = true;
+		drain(this);
+	}
+	close() {
+		this[CLOSED] = true;
+		const peer = this[ENTANGLED];
+		this[ENTANGLED] = null;
+		if (peer) peer[ENTANGLED] = null;
+	}
+	postMessage(data) {
+		const peer = this[ENTANGLED];
+		if (!peer || peer[CLOSED]) return;
+		peer[QUEUE].push(data);
+		if (peer[STARTED]) drain(peer);
+	}
+	addEventListener(type, listener) {
+		if (type !== "message" || !listener) return;
+		this[LISTENERS].push(listener);
+	}
+	removeEventListener(type, listener) {
+		if (type !== "message") return;
+		const at = this[LISTENERS].indexOf(listener);
+		if (at !== -1) this[LISTENERS].splice(at, 1);
+	}
+	dispatchEvent(event) {
+		deliver(this, event);
+		return true;
+	}
+};
+function drain(port) {
+	if (port[QUEUE].length === 0) return;
+	const data = port[QUEUE].shift();
+	setTimeout(() => {
+		if (port[CLOSED]) return;
+		deliver(port, {
+			type: "message",
+			data,
+			target: port,
+			ports: []
+		});
+		drain(port);
+	}, 0);
+}
+function deliver(port, event) {
+	if (typeof port.onmessage === "function") port.onmessage(event);
+	for (const listener of port[LISTENERS].slice()) if (typeof listener === "function") listener.call(port, event);
+	else if (listener && typeof listener.handleEvent === "function") listener.handleEvent(event);
+}
+var MessageChannel = class {
+	constructor() {
+		this.port1 = new MessagePort();
+		this.port2 = new MessagePort();
+		this.port1[ENTANGLED] = this.port2;
+		this.port2[ENTANGLED] = this.port1;
+	}
+};
+//#endregion
+//#region ../../server/guest-surface/locale-methods.js
+function installUnsupportedLocaleMethods(scope, methods, remedy) {
+	const replaced = [];
+	for (const { target, name } of methods) {
+		const owner = resolve(scope, target);
+		if (!owner || typeof owner[name] !== "function") continue;
+		const message = `wawesome: ${target}.${name} is not supported — ${remedy}.`;
+		const thrower = function() {
+			throw new TypeError(message);
+		};
+		Object.defineProperty(thrower, "name", {
+			value: name,
+			configurable: true
+		});
+		replaced.push({
+			target,
+			name,
+			owner,
+			previous: Object.getOwnPropertyDescriptor(owner, name)
+		});
+		Object.defineProperty(owner, name, {
+			value: thrower,
+			writable: true,
+			enumerable: false,
+			configurable: true
+		});
+	}
+	return replaced;
+}
+function resolve(scope, target) {
+	return target.split(".").reduce((current, part) => current == null ? current : current[part], scope);
+}
+//#endregion
+//#region ../../server/guest-surface/surface.json
+var globals = [
+	{
+		"name": "MessageChannel",
+		"status": "shim",
+		"shim": "message-channel",
+		"why": "The engine has none. react-dom/server.browser constructs one at module scope, so a bundle that reaches for it does not evaluate at all."
+	},
+	{
+		"name": "MessagePort",
+		"status": "shim",
+		"shim": "message-channel",
+		"why": "The other half of the pair: a port handed to code that checks what it received has to be a real constructor."
+	},
+	{
+		"name": "Intl",
+		"status": "unsupported",
+		"remedy": "bundle an Intl polyfill, for example @formatjs/intl-numberformat",
+		"providedBy": [
+			"intl",
+			"full-icu",
+			"@formatjs/intl",
+			"@formatjs/intl-*",
+			"intl-pluralrules",
+			"intl-locales-supported",
+			"intl-segmenter-polyfill"
+		]
+	}
+];
+var methods = [
+	{
+		"target": "Number.prototype",
+		"name": "toLocaleString"
+	},
+	{
+		"target": "Date.prototype",
+		"name": "toLocaleString"
+	},
+	{
+		"target": "Date.prototype",
+		"name": "toLocaleDateString"
+	},
+	{
+		"target": "Date.prototype",
+		"name": "toLocaleTimeString"
+	},
+	{
+		"target": "String.prototype",
+		"name": "toLocaleLowerCase"
+	},
+	{
+		"target": "String.prototype",
+		"name": "toLocaleUpperCase"
+	}
+];
+var methodRemedy$1 = "the engine carries no ICU, so it ignores the locale and returns an unlocalised string; format the value yourself, or bundle a formatting library and call it directly";
+//#endregion
+//#region src/guest-surface.ts
+function declaredGlobals() {
+	return globals;
+}
+function declaredMethods() {
+	return methods;
+}
+function methodRemedy() {
+	return methodRemedy$1;
+}
+function unsupportedGlobals() {
+	return declaredGlobals().filter((entry) => entry.status === "unsupported");
+}
+function shimmedGlobals() {
+	return declaredGlobals().filter((entry) => entry.status === "shim");
+}
+//#endregion
+//#region src/guest-parity.ts
+const SHIMS = {
+	MessageChannel,
+	MessagePort
+};
+function applyGuestParity(options = {}) {
+	const scope = globalThis;
+	const declared = declaredPackages(options.projectDir ?? process.cwd());
+	const undo = [];
+	const removed = [];
+	const exempted = [];
+	for (const entry of unsupportedGlobals()) {
+		if (isPolyfilled(entry, declared)) {
+			exempted.push(entry.name);
+			continue;
+		}
+		const descriptor = Object.getOwnPropertyDescriptor(scope, entry.name);
+		if (!descriptor) continue;
+		undo.push(() => Object.defineProperty(scope, entry.name, descriptor));
+		delete scope[entry.name];
+		removed.push(entry.name);
+	}
+	const shimmed = [];
+	for (const entry of shimmedGlobals()) {
+		const replacement = SHIMS[entry.name];
+		if (!replacement) throw new Error(`wawesome: the guest surface declares ${entry.name} as a platform shim, and no implementation is registered for it.`);
+		const descriptor = Object.getOwnPropertyDescriptor(scope, entry.name);
+		undo.push(() => {
+			if (descriptor) Object.defineProperty(scope, entry.name, descriptor);
+			else delete scope[entry.name];
+		});
+		scope[entry.name] = replacement;
+		shimmed.push(entry.name);
+	}
+	const replaced = installUnsupportedLocaleMethods(scope, declaredMethods(), methodRemedy());
+	undo.push(() => {
+		for (const { owner, name, previous } of replaced) if (previous) Object.defineProperty(owner, name, previous);
+	});
+	return {
+		removed,
+		shimmed,
+		replacedMethods: replaced.map(({ target, name }) => `${target}.${name}`),
+		exempted,
+		restore() {
+			for (const step of undo.reverse()) step();
+			undo.length = 0;
+		}
+	};
+}
+/**
+* Read from the manifest the polyfill is already declared in, so parity has no
+* switch of its own that can drift from what the project actually bundles.
+*/
+function isPolyfilled(entry, declared) {
+	return (entry.providedBy ?? []).some((pattern) => declared.some((name) => matches(pattern, name)));
+}
+function matches(pattern, name) {
+	if (!pattern.endsWith("*")) return pattern === name;
+	return name.startsWith(pattern.slice(0, -1));
+}
+function declaredPackages(projectDir) {
+	const manifest = path.join(projectDir, "package.json");
+	if (!fs.existsSync(manifest)) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+	} catch {
+		return [];
+	}
+	return [
+		"dependencies",
+		"devDependencies",
+		"optionalDependencies"
+	].flatMap((field) => {
+		const deps = parsed[field];
+		return typeof deps === "object" && deps !== null ? Object.keys(deps) : [];
+	});
+}
+//#endregion
+export { applyGuestParity as t };

package/dist/guest-parity.d.mts

@@ -0,0 +1,16 @@
+//#region src/guest-parity.d.ts
+interface GuestParityOptions {
+  /** Where the polyfills are declared. Defaults to the working directory. */
+  projectDir?: string;
+}
+interface GuestParity {
+  removed: string[];
+  shimmed: string[];
+  replacedMethods: string[];
+  /** Left in place because the project bundles a polyfill for them. */
+  exempted: string[];
+  restore(): void;
+}
+declare function applyGuestParity(options?: GuestParityOptions): GuestParity;
+//#endregion
+export { GuestParity, GuestParityOptions, applyGuestParity };

package/dist/guest-parity.mjs

@@ -0,0 +1,2 @@
+import { t as applyGuestParity } from "./guest-parity-CWuYJPbS.mjs";
+export { applyGuestParity };

package/dist/index.mjs

@@ -181,7 +181,7 @@ async function buildJs(entryInput, options) {
 * that has to name this version — `--version`, the dependency a scaffolded
 * project pins — reads it here, so a release bumps one file.
 */
-const CLI_VERSION = "0.0.14";
+const CLI_VERSION = "0.0.15";
 //#endregion
 //#region src/prompt.ts
 /**

package/dist/vitest-setup.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/vitest-setup.mjs

@@ -0,0 +1,5 @@
+import { t as applyGuestParity } from "./guest-parity-CWuYJPbS.mjs";
+//#region src/vitest-setup.ts
+applyGuestParity();
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wawesome",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "CLI tool for building and deploying serverless functions on wawesome.io platform",
   "type": "module",
   "bin": {
@@ -8,6 +8,21 @@
   },
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./guest-parity": {
+      "types": "./dist/guest-parity.d.mts",
+      "default": "./dist/guest-parity.mjs"
+    },
+    "./vitest-setup": {
+      "types": "./dist/vitest-setup.d.mts",
+      "default": "./dist/vitest-setup.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin",
     "dist"