syntaxase-wasm 0.0.0

package/README.md

@@ -0,0 +1,62 @@
+# Syntaxase
+
+Lightning-fast type stripping and JSX lowering.
+
+Named like an enzyme, Syntaxase removes erasable TypeScript syntax and lowers
+supported TypeScript and JSX runtime constructs.
+
+## Install
+
+```sh
+npm install syntaxase-wasm
+```
+
+## Usage
+
+```js
+import { stripTypes, transform } from "syntaxase-wasm";
+
+const stripped = stripTypes(`
+interface User { name: string }
+const user: User = { name: "Ada" };
+`);
+
+const transformed = transform(`const view: JSX.Element = <h1>Hello</h1>;`, { jsx: true });
+```
+
+## TypeScript syntax
+
+`stripTypes` erases fixed-width TypeScript syntax while preserving source
+length and line layout. Use it with source accepted by TypeScript's
+[`erasableSyntaxOnly`](https://www.typescriptlang.org/tsconfig/erasableSyntaxOnly.html)
+option. It does not validate that constraint: runtime TypeScript constructs such
+as enums may remain unchanged or lose TypeScript-only modifiers without gaining
+the JavaScript code needed to preserve their semantics.
+
+`transform` additionally lowers supported runtime TypeScript constructs and,
+when enabled, JSX.
+
+## JSX options
+
+| `options.jsx`              | Behavior                                          | Defaults and supported fields                                   |
+| -------------------------- | ------------------------------------------------- | --------------------------------------------------------------- |
+| omitted or `false`         | Parse TypeScript without JSX                      | None                                                            |
+| `true`                     | Lower JSX with the automatic production runtime   | `importSource: "react"`                                         |
+| `{ runtime: "automatic" }` | Lower JSX with the automatic runtime              | `development: false`, `importSource: "react"`                   |
+| `{ runtime: "classic" }`   | Lower JSX to factory calls without adding imports | `pragma: "React.createElement"`, `pragmaFrag: "React.Fragment"` |
+| `{ runtime: "preserve" }`  | Parse JSX and leave it in the output              | No additional fields                                            |
+
+Automatic development mode imports `jsxDEV` from
+`<importSource>/jsx-dev-runtime`; production mode imports `jsx` and `jsxs` from
+`<importSource>/jsx-runtime`. The default therefore requires React's JSX runtime
+to be installed. Set `importSource` for another compatible runtime.
+
+`development` is supported only by the automatic runtime. `pragma` and
+`pragmaFrag` are supported only by the classic runtime.
+
+## Diagnostics and errors
+
+The JavaScript API returns transformed strings only. Parser recovery diagnostics
+are not exposed, so malformed input can still produce output. Use a TypeScript
+checker or another parser when validation is required. Invalid API arguments and
+internal transform failures throw.

package/index.d.ts

@@ -0,0 +1,35 @@
+/** JSX lowering strategy used by every Syntaxase JavaScript package. */
+export type JSXRuntime = "automatic" | "classic" | "preserve";
+
+export type JSXConfig =
+	| {
+			runtime?: "automatic";
+			development?: boolean;
+			importSource?: string;
+			pragma?: never;
+			pragmaFrag?: never;
+	  }
+	| {
+			runtime: "classic";
+			development?: never;
+			importSource?: never;
+			pragma?: string;
+			pragmaFrag?: string;
+	  }
+	| {
+			runtime: "preserve";
+			development?: never;
+			importSource?: never;
+			pragma?: never;
+			pragmaFrag?: never;
+	  };
+
+export interface TransformOptions {
+	jsx?: boolean | JSXConfig;
+}
+
+/** Transform erasable TypeScript and supported runtime TypeScript/JSX syntax to JavaScript. */
+export function transform(sourceText: string, options?: TransformOptions): string;
+
+/** Erase only fixed-width TypeScript syntax while preserving source length and line layout. */
+export function stripTypes(sourceText: string): string;

package/index.js

@@ -0,0 +1,57 @@
+import wasmBytes from "./wasm.js";
+import { assertSourceText, MODE_STRIP_TYPES, resolveTransformOptions } from "./options.js";
+
+const wasmModule = new WebAssembly.Module(wasmBytes);
+const wasmInstance = new WebAssembly.Instance(wasmModule);
+const { alloc, free, memory, run } = wasmInstance.exports;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+const MAX_WASM_LENGTH = 0xffff_ffff;
+
+/** Transform erasable TypeScript and supported runtime TypeScript/JSX syntax to JavaScript. */
+export function transform(sourceText, options = {}) {
+	assertSourceText(sourceText);
+	const normalized = resolveTransformOptions(options);
+	return invoke(sourceText, normalized.mode, normalized.first, normalized.second);
+}
+
+/** Erase only fixed-width TypeScript syntax while preserving source length and line layout. */
+export function stripTypes(sourceText) {
+	assertSourceText(sourceText);
+	return invoke(sourceText, MODE_STRIP_TYPES, "", "");
+}
+
+function invoke(sourceText, mode, firstOption, secondOption) {
+	const source = encoder.encode(sourceText);
+	const first = encoder.encode(firstOption);
+	const second = encoder.encode(secondOption);
+	const inputLength = source.length + first.length + second.length;
+	if (inputLength > MAX_WASM_LENGTH) {
+		throw new RangeError("encoded transform input exceeds WebAssembly memory limits");
+	}
+
+	const allocationLength = Math.max(inputLength, 1);
+	const inputPointer = alloc(allocationLength) >>> 0;
+	let outputPointer = 0;
+	let outputLength = 0;
+	try {
+		const input = new Uint8Array(memory.buffer, inputPointer, inputLength);
+		input.set(source, 0);
+		input.set(first, source.length);
+		input.set(second, source.length + first.length);
+
+		outputPointer = run(inputPointer, source.length, first.length, second.length, mode) >>> 0;
+		if (outputPointer === 0) {
+			throw new Error("Syntaxase WebAssembly transform failed");
+		}
+
+		const header = new DataView(memory.buffer, outputPointer, 4);
+		outputLength = header.getUint32(0, true);
+		const output = new Uint8Array(memory.buffer, outputPointer + 4, outputLength);
+		return decoder.decode(output);
+	} finally {
+		if (outputPointer !== 0) free(outputPointer, outputLength + 4);
+		free(inputPointer, allocationLength);
+	}
+}

package/options.js

@@ -0,0 +1,186 @@
+// Canonical option normalization shared by all JavaScript package boundaries.
+const MODE_TRANSFORM = 0;
+const MODE_AUTOMATIC = 1;
+const MODE_AUTOMATIC_DEVELOPMENT = 2;
+const MODE_CLASSIC = 3;
+const MODE_PRESERVE = 4;
+export const MODE_STRIP_TYPES = 5;
+
+const IDENTIFIER_NAME = /^[$_\p{ID_Start}][$\u200c\u200d_\p{ID_Continue}]*$/u;
+const RESERVED_IDENTIFIER_REFERENCES = new Set([
+	"await",
+	"break",
+	"case",
+	"catch",
+	"class",
+	"const",
+	"continue",
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"export",
+	"extends",
+	"false",
+	"finally",
+	"for",
+	"function",
+	"if",
+	"implements",
+	"import",
+	"in",
+	"instanceof",
+	"interface",
+	"let",
+	"new",
+	"null",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"return",
+	"static",
+	"super",
+	"switch",
+	"this",
+	"throw",
+	"true",
+	"try",
+	"typeof",
+	"var",
+	"void",
+	"while",
+	"with",
+	"yield",
+]);
+const JSX_CONFIG_KEYS = new Set(["runtime", "development", "importSource", "pragma", "pragmaFrag"]);
+const JSX_RUNTIMES = new Set(["automatic", "classic", "preserve"]);
+
+export function assertSourceText(sourceText) {
+	if (typeof sourceText !== "string") {
+		throw new TypeError("sourceText must be a string");
+	}
+}
+
+export function resolveTransformOptions(options) {
+	assertOptions(options);
+	return resolveJSXConfig(options.jsx);
+}
+
+function assertOptions(options) {
+	if (options === null || typeof options !== "object" || Array.isArray(options)) {
+		throw new TypeError("transform options must be an object");
+	}
+	for (const key of Reflect.ownKeys(options)) {
+		if (key !== "jsx") {
+			throw new TypeError(`transform options contains unknown option ${String(key)}`);
+		}
+	}
+}
+
+function resolveJSXConfig(value) {
+	if (value === undefined || value === false) {
+		return { mode: MODE_TRANSFORM, first: "", second: "" };
+	}
+	if (value === true) {
+		return { mode: MODE_AUTOMATIC, first: "react", second: "" };
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		throw new TypeError("transform options.jsx must be a boolean or an object");
+	}
+
+	assertKnownJSXKeys(value);
+	const runtime = readRuntime(value);
+	const importSource = readString(value, "importSource");
+	const pragma = readMemberExpression(value, "pragma");
+	const pragmaFrag = readMemberExpression(value, "pragmaFrag");
+
+	if (runtime === "automatic") {
+		const development = readBoolean(value, "development", false);
+		assertAbsent(value, "pragma", runtime);
+		assertAbsent(value, "pragmaFrag", runtime);
+		return {
+			mode: development ? MODE_AUTOMATIC_DEVELOPMENT : MODE_AUTOMATIC,
+			first: importSource ?? "react",
+			second: "",
+		};
+	}
+	if (runtime === "classic") {
+		assertAbsent(value, "development", runtime);
+		assertAbsent(value, "importSource", runtime);
+		return {
+			mode: MODE_CLASSIC,
+			first: pragma ?? "React.createElement",
+			second: pragmaFrag ?? "React.Fragment",
+		};
+	}
+
+	assertAbsent(value, "development", runtime);
+	assertAbsent(value, "importSource", runtime);
+	assertAbsent(value, "pragma", runtime);
+	assertAbsent(value, "pragmaFrag", runtime);
+	return { mode: MODE_PRESERVE, first: "", second: "" };
+}
+
+function assertKnownJSXKeys(config) {
+	for (const key of Reflect.ownKeys(config)) {
+		if (typeof key !== "string" || !JSX_CONFIG_KEYS.has(key)) {
+			throw new TypeError(`transform options.jsx contains unknown option ${String(key)}`);
+		}
+	}
+}
+
+function readRuntime(config) {
+	if (!Object.hasOwn(config, "runtime")) return "automatic";
+	const runtime = config.runtime;
+	if (typeof runtime !== "string" || !JSX_RUNTIMES.has(runtime)) {
+		throw new TypeError('transform options.jsx.runtime must be "automatic", "classic", or "preserve"');
+	}
+	return runtime;
+}
+
+function readBoolean(config, key, defaultValue) {
+	if (!Object.hasOwn(config, key)) return defaultValue;
+	const value = config[key];
+	if (typeof value !== "boolean") {
+		throw new TypeError(`transform options.jsx.${key} must be a boolean`);
+	}
+	return value;
+}
+
+function readString(config, key) {
+	if (!Object.hasOwn(config, key)) return undefined;
+	const value = config[key];
+	if (typeof value !== "string" || value.length === 0) {
+		throw new TypeError(`transform options.jsx.${key} must be a non-empty string`);
+	}
+	return value;
+}
+
+function readMemberExpression(config, key) {
+	if (!Object.hasOwn(config, key)) return undefined;
+	const value = config[key];
+	if (typeof value !== "string" || !isDottedMemberExpression(value)) {
+		throw new TypeError(`transform options.jsx.${key} must be an identifier or dotted member expression`);
+	}
+	return value;
+}
+
+function isDottedMemberExpression(value) {
+	const segments = value.split(".");
+	const root = segments[0];
+	if (root === undefined || !isIdentifierReference(root)) return false;
+	return segments.every((segment) => IDENTIFIER_NAME.test(segment));
+}
+
+function isIdentifierReference(value) {
+	return IDENTIFIER_NAME.test(value) && !RESERVED_IDENTIFIER_REFERENCES.has(value);
+}
+
+function assertAbsent(config, key, runtime) {
+	if (Object.hasOwn(config, key)) {
+		throw new TypeError(`transform options.jsx.${String(key)} is not supported with ${runtime} runtime`);
+	}
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "syntaxase-wasm",
+	"version": "0.0.0",
+	"description": "Lightning-fast type stripping and JSX lowering",
+	"license": "MIT",
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/magic-akari"
+	},
+	"type": "module",
+	"main": "index.js",
+	"types": "index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		}
+	},
+	"files": ["index.js", "index.d.ts", "options.js", "wasm.js"]
+}