syntaxase 0.0.0 → 0.1.1

package/README.md

@@ -1,6 +1,67 @@
 # Syntaxase
 
-> [!WARNING]
-> Work in progress. This package is not ready for use yet.
+Lightning-fast type stripping and JSX lowering.
 
-A tiny syntax-only transformer for TypeScript and JSX.
+Named like an enzyme, Syntaxase removes erasable TypeScript syntax and lowers
+supported TypeScript and JSX runtime constructs.
+
+## Install
+
+```sh
+npm install syntaxase
+```
+
+## Usage
+
+```js
+import { stripTypes, transform } from "syntaxase";
+
+const stripped = stripTypes(`
+interface User { name: string }
+const user: User = { name: "Ada" };
+`);
+
+const strippedTsx = stripTypes(`const view = <Card<User> user={user as User} />;`, { lang: "tsx" });
+
+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.
+
+By default, `stripTypes` parses TypeScript without JSX. Pass `{ lang: "tsx" }`
+to strip TypeScript syntax from TSX while leaving JSX unchanged.
+
+`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/binding.js

@@ -0,0 +1,63 @@
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const { platform, arch } = process;
+
+const isFileMusl = (f) => f.includes('libc.musl-') || f.includes('ld-musl-');
+
+function isMusl() {
+  if (platform !== 'linux') return false;
+
+  try {
+    if (readFileSync('/usr/bin/ldd', 'utf-8').includes('musl')) return true;
+  } catch {}
+
+  try {
+    const report = typeof process.report?.getReport === 'function'
+      ? process.report.getReport()
+      : null;
+    if (report) {
+      const header = typeof report === 'string' ? JSON.parse(report).header : report.header;
+      if (header?.glibcVersionRuntime) return false;
+      if (Array.isArray(report.sharedObjects) && report.sharedObjects.some(isFileMusl)) return true;
+    }
+  } catch {}
+
+  try {
+    return execSync('ldd --version', { encoding: 'utf8' }).includes('musl');
+  } catch {}
+
+  return false;
+}
+
+function loadBinding() {
+  const errors = [];
+  const libc = platform === 'linux' ? (isMusl() ? '-musl' : '-gnu') : '';
+  const suffix = `${platform}-${arch}${libc}`;
+
+  try {
+    return require(join(__dirname, '@syntaxase', 'binding-' + suffix, 'syntaxase.node'));
+  } catch (e) {
+    errors.push(e);
+  }
+
+  try {
+    return require('@syntaxase/binding-' + suffix + '/syntaxase.node');
+  } catch (e) {
+    errors.push(e);
+  }
+
+  throw new Error(
+    `Failed to load native binding for ${platform}-${arch}.\n` +
+    `If this persists, try removing node_modules and reinstalling.\n` +
+    errors.map(e => `  - ${e.message}`).join('\n'),
+    { cause: errors[errors.length - 1] }
+  );
+}
+
+export default loadBinding();

package/index.d.ts

@@ -0,0 +1,39 @@
+/** 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;
+}
+
+export interface StripTypesOptions {
+	lang?: "ts" | "tsx";
+}
+
+/** 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, options?: StripTypesOptions): string;

package/index.js

@@ -1 +1,25 @@
-// WIP
+import binding from "./binding.js";
+import { assertSourceText, resolveStripTypesOptions, resolveTransformOptions } from "./options.js";
+
+const encoder = new TextEncoder();
+const empty = new Uint8Array();
+
+/** 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, options = {}) {
+	assertSourceText(sourceText);
+	return invoke(sourceText, resolveStripTypesOptions(options), "", "");
+}
+
+function invoke(sourceText, mode, firstOption, secondOption) {
+	const source = encoder.encode(sourceText);
+	const first = firstOption.length === 0 ? empty : encoder.encode(firstOption);
+	const second = secondOption.length === 0 ? empty : encoder.encode(secondOption);
+	return binding.run(source, mode, first, second);
+}

package/options.js

@@ -0,0 +1,206 @@
+// 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;
+export const MODE_STRIP_TYPES_TSX = 6;
+
+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);
+}
+
+export function resolveStripTypesOptions(options) {
+	if (options === null || typeof options !== "object" || Array.isArray(options)) {
+		throw new TypeError("stripTypes options must be an object");
+	}
+	for (const key of Reflect.ownKeys(options)) {
+		if (key !== "lang") {
+			throw new TypeError(`stripTypes options contains unknown option ${String(key)}`);
+		}
+	}
+
+	if (!Object.hasOwn(options, "lang") || options.lang === "ts") {
+		return MODE_STRIP_TYPES;
+	}
+	if (options.lang === "tsx") {
+		return MODE_STRIP_TYPES_TSX;
+	}
+	throw new TypeError('stripTypes options.lang must be "ts" or "tsx"');
+}
+
+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

@@ -1,20 +1,48 @@
 {
   "name": "syntaxase",
-  "version": "0.0.0",
-  "description": "A tiny syntax-only transformer for TypeScript and JSX.",
+  "version": "0.1.1",
+  "description": "Lightning-fast type stripping and JSX lowering",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magic-akari/syntaxase.git"
+  },
   "type": "module",
-  "exports": "./index.js",
+  "main": "index.js",
+  "types": "index.d.ts",
   "files": [
-    "index.js"
+    "index.js",
+    "index.d.ts",
+    "binding.js",
+    "options.js"
   ],
-  "engines": {
-    "node": ">=18"
+  "optionalDependencies": {
+    "@syntaxase/binding-linux-x64-gnu": "0.1.1",
+    "@syntaxase/binding-linux-arm64-gnu": "0.1.1",
+    "@syntaxase/binding-linux-arm-gnu": "0.1.1",
+    "@syntaxase/binding-linux-x64-musl": "0.1.1",
+    "@syntaxase/binding-linux-arm64-musl": "0.1.1",
+    "@syntaxase/binding-linux-arm-musl": "0.1.1",
+    "@syntaxase/binding-darwin-x64": "0.1.1",
+    "@syntaxase/binding-darwin-arm64": "0.1.1",
+    "@syntaxase/binding-win32-x64": "0.1.1",
+    "@syntaxase/binding-win32-arm64": "0.1.1",
+    "@syntaxase/binding-freebsd-x64": "0.1.1"
   },
+  "author": "magic-akari <akari.ccino@gmail.com>",
+  "homepage": "https://github.com/magic-akari/syntaxase",
   "keywords": [
     "typescript",
+    "tsx",
     "jsx",
     "transformer",
-    "transpiler"
+    "strip-types"
   ],
-  "license": "MIT"
+  "publishConfig": {
+    "access": "public"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/magic-akari"
+  }
 }