@zpl-toolchain/core 0.1.1

package/README.md

@@ -0,0 +1,67 @@
+# @zpl-toolchain/core
+
+TypeScript wrapper for the ZPL toolchain WASM bindings. Provides full TypeScript types and an ergonomic API for parsing, validating, formatting, and explaining ZPL code.
+
+## Installation
+
+```bash
+npm install @zpl-toolchain/core
+```
+
+## Usage
+
+```ts
+import { init, parse, format, validate, explain } from "@zpl-toolchain/core";
+
+// Initialize WASM module (required once before calling any function)
+await init();
+
+// Parse ZPL
+const result = parse("^XA^FDHello^FS^XZ");
+console.log(result.ast.labels.length); // 1
+
+// Format ZPL
+const formatted = format("^XA^FD Hello ^FS^XZ", "label");
+
+// Validate ZPL
+const validation = validate("^XA^FDHello^FS^XZ");
+console.log(validation.ok); // true
+
+// Explain a diagnostic code
+const explanation = explain("ZPL1201");
+```
+
+## API
+
+| Function | Signature | Description |
+|---|---|---|
+| `init()` | `() → Promise<void>` | Initialize WASM module (call once) |
+| `parse(input)` | `(string) → ParseResult` | Parse ZPL, return AST + diagnostics |
+| `parseWithTables(input, tablesJson)` | `(string, string) → ParseResult` | Parse with explicit parser tables |
+| `validate(input, profileJson?)` | `(string, string?) → ValidationResult` | Parse + validate |
+| `format(input, indent?)` | `(string, IndentStyle?) → string` | Format ZPL |
+| `explain(id)` | `(string) → string \| null` | Explain a diagnostic code |
+
+## Types
+
+All types are exported and match the Rust AST serialization format:
+
+- **`Node`** — discriminated union on `kind`: `CommandNode | FieldDataNode | RawDataNode | TriviaNode`
+- **`Severity`** — `"error" | "warn" | "info"` (lowercase, matching Rust serde)
+- **`Presence`** — `"unset" | "empty" | "value"` (lowercase)
+- **`IndentStyle`** — `"none" | "label" | "field"`
+
+See `src/index.ts` for the full type definitions.
+
+## Build from source
+
+```bash
+# Install dependencies
+npm install
+
+# Build WASM artifacts (requires wasm-pack)
+npm run build:wasm
+
+# Build TypeScript package
+npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @zpl-toolchain/core — TypeScript bindings for the ZPL toolchain.
+ *
+ * This package wraps the WASM build of the Rust ZPL toolchain, exposing
+ * parse, validate, format, and explain functions with full TypeScript types.
+ *
+ * @example
+ * ```ts
+ * import { init, parse, format } from "@zpl-toolchain/core";
+ *
+ * // Initialize WASM (required before calling any function)
+ * await init();
+ *
+ * const result = parse("^XA^FDHello^FS^XZ");
+ * console.log(result.ast.labels);
+ *
+ * const formatted = format("^XA^FD Hello ^FS^XZ");
+ * console.log(formatted);
+ * ```
+ */
+/** Byte range in the source input. */
+export interface Span {
+    start: number;
+    end: number;
+}
+/** Argument presence state. Serialized as lowercase by Rust. */
+export type Presence = "unset" | "empty" | "value";
+/** A parsed argument slot. */
+export interface ArgSlot {
+    /** Parameter key name (absent when not defined by spec). */
+    key?: string | null;
+    /** Whether the argument was provided, empty, or not present. */
+    presence: Presence;
+    /** The argument value (absent when presence is "unset" or "empty"). */
+    value?: string | null;
+}
+/**
+ * AST node — discriminated on the `kind` field.
+ *
+ * Rust serializes `Node` with `#[serde(tag = "kind")]` (internally tagged),
+ * producing JSON like `{"kind": "Command", "code": "^XA", ...}`.
+ */
+export type Node = CommandNode | FieldDataNode | RawDataNode | TriviaNode;
+export interface CommandNode {
+    kind: "Command";
+    code: string;
+    args: ArgSlot[];
+    span: Span;
+}
+export interface FieldDataNode {
+    kind: "FieldData";
+    content: string;
+    /** Whether `^FH` hex escapes have been applied. */
+    hex_escaped: boolean;
+    span: Span;
+}
+export interface RawDataNode {
+    kind: "RawData";
+    /** The command that initiated raw data collection (e.g., "^GF"). */
+    command: string;
+    /** Raw payload data (absent if command header had no trailing data). */
+    data?: string | null;
+    span: Span;
+}
+export interface TriviaNode {
+    kind: "Trivia";
+    text: string;
+    span: Span;
+}
+/** A single ZPL label (^XA ... ^XZ block). */
+export interface Label {
+    nodes: Node[];
+}
+/** Top-level AST for a ZPL document. */
+export interface Ast {
+    labels: Label[];
+}
+/** Diagnostic severity level. Serialized as lowercase by Rust. */
+export type Severity = "error" | "warn" | "info";
+/** A diagnostic message from the parser or validator. */
+export interface Diagnostic {
+    id: string;
+    severity: Severity;
+    message: string;
+    span?: Span;
+    context?: Record<string, string>;
+}
+/** Result of parsing a ZPL string. */
+export interface ParseResult {
+    ast: Ast;
+    diagnostics: Diagnostic[];
+}
+/** Result of validating a ZPL string. */
+export interface ValidationResult {
+    ok: boolean;
+    issues: Diagnostic[];
+}
+/** Indentation style for the formatter. */
+export type IndentStyle = "none" | "label" | "field";
+/**
+ * Initialize the WASM module. Must be called once before using any other
+ * function. Safe to call multiple times (subsequent calls are no-ops).
+ *
+ * @example
+ * ```ts
+ * await init();
+ * ```
+ */
+export declare function init(): Promise<void>;
+/**
+ * Parse a ZPL string and return the AST with diagnostics.
+ *
+ * Uses embedded parser tables for spec-driven parsing.
+ */
+export declare function parse(input: string): ParseResult;
+/**
+ * Parse a ZPL string with explicitly provided parser tables (JSON string).
+ */
+export declare function parseWithTables(input: string, tablesJson: string): ParseResult;
+/**
+ * Parse and validate a ZPL string.
+ *
+ * @param input ZPL source code.
+ * @param profileJson Optional printer profile JSON string.
+ */
+export declare function validate(input: string, profileJson?: string): ValidationResult;
+/**
+ * Format a ZPL string (normalize whitespace, one command per line).
+ *
+ * @param input ZPL source code.
+ * @param indent Indentation style: "none" (default), "label", or "field".
+ */
+export declare function format(input: string, indent?: IndentStyle): string;
+/**
+ * Explain a diagnostic code (e.g., "ZPL1201").
+ *
+ * @returns The explanation string, or null if the code is unknown.
+ */
+export declare function explain(id: string): string | null;

package/dist/index.js

@@ -0,0 +1,96 @@
+/**
+ * @zpl-toolchain/core — TypeScript bindings for the ZPL toolchain.
+ *
+ * This package wraps the WASM build of the Rust ZPL toolchain, exposing
+ * parse, validate, format, and explain functions with full TypeScript types.
+ *
+ * @example
+ * ```ts
+ * import { init, parse, format } from "@zpl-toolchain/core";
+ *
+ * // Initialize WASM (required before calling any function)
+ * await init();
+ *
+ * const result = parse("^XA^FDHello^FS^XZ");
+ * console.log(result.ast.labels);
+ *
+ * const formatted = format("^XA^FD Hello ^FS^XZ");
+ * console.log(formatted);
+ * ```
+ */
+// ── WASM Module ─────────────────────────────────────────────────────────
+// The WASM module is loaded lazily. In a bundler environment (webpack, vite,
+// etc.), the WASM file is typically handled as an asset. For Node.js, the
+// WASM file must be on disk.
+//
+// We use dynamic import so the WASM binary is only fetched when init() is
+// called, keeping the initial bundle lightweight.
+let wasmModule = null;
+/**
+ * Initialize the WASM module. Must be called once before using any other
+ * function. Safe to call multiple times (subsequent calls are no-ops).
+ *
+ * @example
+ * ```ts
+ * await init();
+ * ```
+ */
+export async function init() {
+    if (wasmModule)
+        return;
+    // Dynamic import — bundlers will resolve the WASM package
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    wasmModule = await import("../wasm/pkg/zpl_toolchain_wasm");
+}
+function ensureInit() {
+    if (!wasmModule) {
+        throw new Error("@zpl-toolchain/core: WASM not initialized. Call `await init()` first.");
+    }
+    return wasmModule;
+}
+// ── Public API ──────────────────────────────────────────────────────────
+/**
+ * Parse a ZPL string and return the AST with diagnostics.
+ *
+ * Uses embedded parser tables for spec-driven parsing.
+ */
+export function parse(input) {
+    const wasm = ensureInit();
+    return wasm.parse(input);
+}
+/**
+ * Parse a ZPL string with explicitly provided parser tables (JSON string).
+ */
+export function parseWithTables(input, tablesJson) {
+    const wasm = ensureInit();
+    return wasm.parseWithTables(input, tablesJson);
+}
+/**
+ * Parse and validate a ZPL string.
+ *
+ * @param input ZPL source code.
+ * @param profileJson Optional printer profile JSON string.
+ */
+export function validate(input, profileJson) {
+    const wasm = ensureInit();
+    return wasm.validate(input, profileJson);
+}
+/**
+ * Format a ZPL string (normalize whitespace, one command per line).
+ *
+ * @param input ZPL source code.
+ * @param indent Indentation style: "none" (default), "label", or "field".
+ */
+export function format(input, indent) {
+    const wasm = ensureInit();
+    return wasm.format(input, indent);
+}
+/**
+ * Explain a diagnostic code (e.g., "ZPL1201").
+ *
+ * @returns The explanation string, or null if the code is unknown.
+ */
+export function explain(id) {
+    const wasm = ensureInit();
+    return wasm.explain(id) ?? null;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@zpl-toolchain/core",
+  "version": "0.1.1",
+  "description": "ZPL II toolchain — parse, validate, and format Zebra Programming Language files",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build:wasm": "wasm-pack build ../../crates/wasm --target bundler --out-dir ../../packages/ts/core/wasm/pkg",
+    "build": "npx tsc",
+    "typecheck": "npx tsc --noEmit",
+    "test": "node --test"
+  },
+  "keywords": [
+    "zpl",
+    "zebra",
+    "label",
+    "printer",
+    "parser",
+    "formatter"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "author": "zpl-toolchain contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trevordcampbell/zpl-toolchain.git",
+    "directory": "packages/ts/core"
+  },
+  "homepage": "https://github.com/trevordcampbell/zpl-toolchain",
+  "bugs": {
+    "url": "https://github.com/trevordcampbell/zpl-toolchain/issues"
+  },
+  "files": [
+    "dist",
+    "wasm/pkg",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {}
+}