DOCSEARCHbyAlgolia
Submit Docs

Perry Compiler Documentation

repository·main·Indexed 26 days ago

https://github.com/perryts/perry

Perry is a compiler that transforms TypeScript into native machine-code executables for macOS, Windows, Linux, iOS, Android, and Web. By utilizing LLVM, it produces high-performance, self-contained binaries that eliminate the need for JavaScript runtimes like Node.js or Bun. The project includes comprehensive benchmarking suites such as App-pattern and Honest Benchmark, as well as a Compiler Output Regression Harness for tracing HIR to LLVM IR and disassembly.

Tokens
267.2K
Snippets
489
Records
1.4K
Agent score
89%

What's inside Perry

  1. Overview of node:buffer granular parity suite

    main

    The node:buffer granular parity suite is a collection of focused Node.js parity test cases designed to validate Perry's node:buffer compatibility layer. The suite ensures that Perry's implementation of the Buffer API behaves identically to Node.js and Deno by using small, deterministic TypeScript programs to isolate failures to specific API families.

    Key areas of coverage include:

    • Encoding & Decoding: base64url decoding, base64 implicit-padding decoding, and encoding-aware byteLength (including astral-char regression handling for ascii, latin1, and binary to match Node's UTF-16 code unit behavior).
    • Buffer Creation & Allocation: Buffer.of, Buffer.from(arrayBuffer, byteOffset, length?) range selection, and large-buffer allocUnsafe/allocUnsafeSlow length parity.
    • Numeric & Array Handling: Numeric slice coercion, bad hex truncation, Buffer iteration, and numeric byte wrapping (e.g., -1 wrapping to ff).
    • Data Integrity: Signed 64-bit endian round-trips.

  2. Overview of node:zlib granular parity suite

    main

    The node:zlib granular parity suite is a collection of focused Node.js parity cases designed to validate Perry's node:zlib compatibility layer. It ensures that Perry's implementation matches the behavior of Node.js (specifically Node 22+ / current LTS) and Deno's node_compat zlib tests.

    All test cases are deterministic, using closed round-trips for encode/decode operations and hex-printed raw-byte assertions to ensure reliable byte-for-byte comparisons against node --experimental-strip-types.

  3. Overview of node:string_decoder parity suite

    main

    The node:string_decoder parity suite provides granular Node.js compatibility test cases for the node:string_decoder module. It is designed to ensure behavior parity with Node.js (specifically targeting Node 22+ and current LTS) regarding incremental multibyte decoding.

    Each test case is small and deterministic, targeting specific API families including:

    • Imports
    • Constructor and encoding normalization
    • UTF-8 chunking
    • UTF-16LE surrogates
    • Base64, hex, latin1, and ascii encodings
    • .end() flush behavior
    • State properties
    • Accepted input views

  4. Overview of node:diagnostics_channel parity suite

    main
    The node:diagnostics_channel granular parity suite provides focused coverage for the node:diagnostics_channel module in Perry. It is designed to ensure parity with Node.js behavior by porting tests from Node.js parallel tests and cross-checking them against Deno's Node compatibility implementation. This suite is used to identify gaps in Perry's implementation of the diagnostics channel API.

  5. Overview of Perry Container Modules

    main

    Perry provides two primary TypeScript modules for managing OCI containers. Both modules execute via a direct Rust backend to avoid the overhead of shell-outs or YAML generation.

    • perry/container: Used for single-container lifecycles. Includes methods for run, create, start, stop, remove, inspect, logs, exec, and image management.
    • perry/compose: Used for multi-service orchestration. Driven by a TypeScript object literal mirroring the Compose spec. Includes methods for up, down, ps, logs, exec, start, stop, restart, and config.

  6. Overview of Perry Native Library Implementations

    main
    Perry provides native Rust implementations of 27 popular npm packages. When imported in TypeScript, these packages are compiled directly to native code using high-performance Rust crates, eliminating the need for a Node.js runtime. This allows for standalone, high-performance native executables.

  7. Overview of the node:path parity suite

    main
    The node:path parity suite is a collection of granular Node.js compatibility test cases for the node:path module. It is designed to ensure that Perry's implementation of node:path matches Node.js behavior. Each test is intentionally small and deterministic, allowing developers to identify specific API shape mismatches rather than broad module failures.

  8. Overview of node:cluster granular parity suite

    main
    The node:cluster granular parity suite provides deterministic differential test cases designed to verify Perry's compatibility with the Node.js node:cluster module. It uses self-contained primary and worker programs, ephemeral TCP ports, and event/IPC completion barriers to ensure reliable testing. This suite is executed via the sequential slow lane in scripts/node_suite_run.py.

  9. Overview of Perry Widgets (WidgetKit)

    main

    Perry's perry/widget module allows you to define home screen widgets using TypeScript. These declarations are compiled into native widget extensions for multiple platforms, eliminating the need to write platform-specific code (like SwiftUI or Android XML) manually.

    Supported platforms include:

    • iOS: WidgetKit extension
    • Android: App Widgets
    • watchOS: Complications
    • Wear OS: Tiles

  10. Overview of node:crypto granular parity suite

    main
    The node:crypto granular parity suite provides deterministic Node.js parity coverage for Perry's node:crypto and WebCrypto compatibility layers. It ensures byte-for-byte output consistency between Node.js and Perry by running curated test cases derived from Node.js, Bun, and Deno compatibility tests.

  11. Overview of node:module granular parity

    main
    The node:module granular parity lane is a testing suite designed to ensure parity with Node.js 26.5.0 (the oracle). It uses deterministic contracts via TypeScript entry points to validate module behavior across different runtimes (Perry, Deno, Bun). The suite uses controlled fixtures for CommonJS, ESM, JSON, package, and source-map testing, ensuring no dependency on external registries, user home directories, or global node_modules.

  12. Overview of `node:wasi` granular parity suite fixtures

    main

    The node:wasi granular parity suite provides 51 deterministic Node 26.5.0 oracle cases to ensure compatibility with Perry's node:wasi layer. The fixtures are organized into five functional groups:

    • classes/: Validates ESM/CommonJS export shapes, constructor/prototype/instance descriptors, subclass construction, and warning-event assertions.
    • constructor/: Validates constructor options (version, args, env, preopens, stdio descriptors), returnOnExit behavior, and option-property access order.
    • imports/: Tests the 46-function preview1 surface, function metadata, namespace identity, wrapper descriptors, and syscall validation.
    • lifecycle/: Covers input/export validation, memory binding, start/initialize exclusivity, entrypoint invocation, return-on-exit behavior, and failure-state transitions.
    • semantics/: Validates UTF-8 encoding for arguments/environment, embedded-NUL termination, and specific behaviors for clock and random (predicate-only/zero-length).