Skip to content
getcarnePublic

About

Yeah, another JavaScript runtime! Written in Nim language

Topics

Resources

Stars

16 stars

Watchers

1 watching

Forks

Latest commit

 

History

145 Commits

Folders and files

Repository files navigation

Carne Logo
Carne /kär-nē/ • a JavaScript runtime 👑 Written in Nim language

nimble install carne / clue install carne --build

API reference
Github Actions Github Actions

Note

Carne is still experimental: it runs on macOS and Linux (Linux needs libjavascriptcoregtk-4.1-dev installed), the std/* API may change between 0.x releases, and a few modules are parse-only in v1 (see the Standard Library notes below). Scripts needing top-level await must wrap in an async IIFE for now. Not recommended for production yet, but the full test suite passes on both platforms and every example below is covered by it.

About

A JavaScript runtime based on JavaScriptCore and Nim! No drama, no overhype. With a rich standard library, so you don't need npm anymore! Still, it ships with an efficient package manager that abolishes node_modules and keeps dependencies in one shared global store instead.

Carne is not a drop-in replacement for Node.js, Bun or Deno, instead it is a runtime with an opinion: most scripts should not need a dependency at all. It trades the npm ocean for a standard library that covers everyday work out of the box, starts in ~8 ms on the back of JavaScriptCore, and stays ~6k lines of Nim, small enough to read in an afternoon. If you want the Node ecosystem, keep Node. If you want a script that just runs, take Carne.

😍 Key Features

  • JavaScript runtime powered by JavaScriptCore
  • Powerful Standard Library fully written in Nim lang
  • Cryptographic library via pkg/nimcypher
  • HTTP/1.1, H/2, UDP, TCP and WebSockets library via pkg/powpow
  • Built-in formatters: yaml, toml, csv, xml, markdown, vcard, feed, sql, css, diff, qr, svg via pkg/openparser (colors is pure JS)
  • Built-in archives and compression: tar, zip, rar, gz, lz4, bz2, brotli via pkg/archive
  • i18n via GNU Gettext PO/MO
  • CSS and JavaScript bundler via pkg/squeezy
  • Built-in database driver and ORM for sqlite and postgres, async + sync (std/db)
  • Multi-worker HTTP serving off one port, with zero-copy file responses (sendfile, ETag/Range)
  • Built-in test runner: carne test discovers and runs tests/**/*.test.js (std/test)
  • Native addons: Nim shared libraries (.addon) with a newAddon author macro, carne build and carne gen addon (examples/addon/)
  • Terminal toolkit: styling, prompts, password reads, CLI arg parsing (std/terminal)
  • Built-in package manager (carne pkg)
    • one shared global store in your home dir, no node_modules, no duplicated installs across projects
    • install (by name or --url), remove, update, list, prune orphans, refresh registry data
    • develop <path> for editable installs from a local directory
    • package.json manifests, npm-spec compliant; public registry at getcarne/carnepkgs
  • Written in Nim language
  • Open Source | MIT License

Usage

A JavaScript runtime in Nim
  (c) OpenPeeps | MIT License
  Build Version: 0.1.5

usage: carne <command> [args] [options]

Scripting:
  run <script.js> [args]    run a .js file (script args pass through verbatim)
  test [file] [...]         run tests/**/*.test.js (or the given file)
  build <input.nim> <output>  compile a native addon (.addon)
    --release               optimized build (-d:release)

Standard library:
  std init                  download JS stdlib (std/*) into ~/.carne/std
  std update                refresh all JS stdlib files
  std list                  show installed JS stdlib version and files

Packages:
  pkg init [dir]            scaffold a new package (wizard, -Y skips it)
    --yes, -Y               skip the wizard, use defaults
  pkg install <spec>        install a package by name, git URL, gh:user/repo alias, name#ref, or name + source URL
    --url:<url>             pin a source URL
  pkg remove <name> [ver]   uninstall one version, or all
    --yes                   skip confirmation prompts
  pkg update [name]         update one package, or all
  pkg list                  list installed packages
  pkg develop [path]        editable install from a local directory
  pkg prune                 remove orphaned packages
    --yes                   skip confirmation prompts
  pkg refresh               re-download registry data
  pkg publish               open a PR adding this package to the registry
    --tags:<list>           comma-separated tags
    --web:<url>             package website URL
    --url:<url>             pin a source URL
    --dry-run               no network, git, or secret changes
    --yes                   skip confirmation prompts

Generating:
  gen docs                  generate API reference into carnedocs/ (JSON and/or HTML)
    --format:<json|html|all>  docs output selection (default: all)
    --out:<dir>             docs output directory (default: carnedocs)
    --entry:<file>          document one file instead of the whole package
  gen ast <file>            dump the JavaScript AST of <file> (JSON or binary .ast)
    --format:<json|bin>     ast output selection (default: json)
    --out:<dir>             ast output directory (default: alongside the input)
  gen addon <dir>           scaffold a native addon project in <dir>

Versioning:
  bump [semver]             bump version in package.json (or a direct dep)
    --level:<level>         major, minor, or patch
    --dep:<name>            bump a direct dependency spec (prefix kept)
  upgrade [version]         self-update carne from GitHub releases (into ~/.carne/bin)
    --dry-run               print resolved URLs only, no changes

Inspect:
  dump [pkg[@ref]]          print package.json (cwd or an installed package)

options:
    --isatty:<true|false>   override TTY detection (default: auto-detect)
  -h, --help                show this help
  --version                 show version

Package manager

A DFS (depth-first search) package manager with one shared global store (~/.carne, no node_modules), built on pkg/datpkgr, the same engine used at tim, clue, bowdy. It installs from both git and npm-style sources:

  • carne pkg install <git-url> (or --url=... to pin a source URL): https:// URLs, git+/git:// transports, git@ and .git URLs, plus forge aliases (gh:user/repo, long form github:; also gl:, cb:, srht:). A #ref suffix pins a branch or tag: carne pkg install gh:user/repo#v1. Works today.
  • The cloned repo must contain a valid package.json at its root; anything else is rejected, not installed.
  • carne pkg install <name>[@range], npm:name@range aliases: resolved through the package registry at getcarne/carnepkgs (source carne, cached at ~/.carne/registries/carne.json; carne pkg refresh re-downloads it).
  • carne pkg develop [path]: editable installs from a local directory (default: current dir).
  • remove, update, list, prune, refresh manage the store.
  • carne bump [semver] [--level=major|minor|patch] [--dep=name]: bumps the version in the local package.json (default: patch; explicit semver sets it). With --dep=name it bumps that direct dependency's spec instead (dependencies, devDependencies, optionalDependencies, peerDependencies), keeping the range prefix (^0.1.0 patch-bumps to ^0.1.1). Only the bumped value changes; formatting is preserved.
  • carne upgrade [version]: self-updates from getcarne/carne releases into ~/.carne/bin (created on first use; add it to PATH). Bare takes the latest release, a version pins one (0.1.3 or v0.1.3); --dry-run prints the URL only. The previous binary is kept as carne.prev.<old>.
  • carne dump [pkg[@ref]]: prints the raw package.json — the one found from the cwd upwards, or an installed package's (develop checkouts included).
  • carne pkg publish [--tags=..] [--web=..] [--url=..] [--dry-run] [--yes]: opens a pull request adding the current package to getcarne/carnepkgs (fork, insert into packages.json in name order, PR against main). description, license and keywords (registry tags) are required in package.json; the repo URL comes from .git/config (remote.origin.url). Auth is the GitHub token on its own line in ~/.carne/.tokens (chmod 600). --dry-run prints the entry without touching the network.

Package imports

Installed packages load through require("pkg/<name>") as CommonJS: entry resolution reads the exports map root first, then main (index.js, src/index.js, <name>.js fallbacks). A @version suffix pins an installed version, pkg/<name>/sub/path reaches inside, and ./... requires work between package files (and from carne run scripts, relative to the script).

const demo = require("pkg/carne_demo_pkg");
console.log(demo.hello("ada")); // hi ada

A @version suffix pins an installed version (require("pkg/greet@0.1.0")), and pkg/<name>/sub/path reaches inside a package.

Only CommonJS v1: ESM (import/export) packages fail with a clear error, as do packages with no loadable entry.

Native addons

Nim shared libraries (.addon) callable from JS, Node-addon style: a package wraps a prebuilt binary with a JS entry that requires it relatively. Authors write newAddon from carne/api/addon (same registerFn types and arity checks as std modules), compile with carne build, and ship the binary beside the wrapper:

import carne/api/addon

newAddon("hello", "0.1.0"):
  exportObject:
    registerFn hello(name: default(string, "world")):
      ## hello([name]) -> greeting string
      return toJS(ctx, "Hello, " & name & "!")
// index.js — the wrapper: scalar type checking lives at the native
// boundary (wrong types throw TypeError), so it only adapts shapes
// and composes behavior.
const native = require("./native/hello.addon");
module.exports = { hello: native.hello };
carne gen addon hello   # scaffold a wrapper package
carne build native/hello.nim native/hello.addon

Building requires carne as a Nim package, via nimble or clue. require("./x.addon") works from any JS file (package or script); one library loads per process with fresh exports per context, and the loader major-matches the addon against the host carne. See examples/addon/ for the full wrapper pattern.

Standard Library

All modules load lazily via the global require("std/<name>"), requiring one costs nothing until first use. Timers are globals (No require needed), Node-style.

The library covers OS and process access, data formats, text processing, crypto, networking, and developer tools:

  • std/env - process info and environment (args, getEnv, putEnv, delEnv, hasEnv, parse/load .env, cwd, exit)
  • std/os - synchronous OS utilities (files, dirs, exec)
  • std/archive - archive creation/extraction and compression (tar, zip, rar, gz, lz4, bz2, brotli)
  • Timers - setTimeout/setInterval/sleep globals, no require needed
  • std/yaml - YAML parsing and serialization
  • std/toml - TOML parsing and serialization
  • std/ical - iCalendar parsing and serialization
  • std/plist - Apple property lists
  • std/bson - BSON parsing and serialization
  • std/csv - CSV parsing
  • std/xml - XML parsing and serialization
  • std/html - HTML parsing (parse-only in v1)
  • std/vcard - vCard contact parsing (parse-only in v1)
  • std/feed - RSS and Atom feed parsing (parse-only in v1)
  • std/sql - SQL parsing and validation (sqlite, postgres, mysql)
  • std/crypto - hashing, AEAD/XChaCha20-Poly1305 + AES-GCM sealing, ed25519/X25519, ECDSA/ECDH, RSA, passwords
  • std/path - file-path and URL parsing (parse-only in v1)
  • std/colors - color parsing, formatting and math (fetched via carne std init)
  • std/css - CSS parsing and declaration validation
  • std/diff - unified diffs
  • std/gettext - .po parsing and translation, .mo file catalogs
  • std/str - string utilities and validators (fetched via carne std init)
  • std/mimetype - MIME type lookup
  • std/benchmark - in-process microbenchmarking
  • std/qr - QR code generation (model2/model1/micro/rmqr/aqr/sqrc), matrix decoding, payload builders
  • std/svg - SVG parsing and serialization
  • std/http - async HTTP client + server (optional worker threads)
  • std/ws - async + sync WebSocket client and server
  • std/tcp - async TCP client + server, optional TLS
  • std/udp - async UDP sockets (bind/connect, rinfo echo)
  • std/uuid - UUID generation (v1-v8) and inspection
  • std/nanoid - URL-friendly id generation
  • std/url - URL parsing and formatting
  • std/watcher - file watching (async watch + sync watchOnce)
  • std/terminal - terminal styling, size, raw output, reads, CLI arg parsing
  • std/test - minimal test runner (test/describe/expect/assert, fetched via carne std init)
  • std/db - async + sync database driver and ORM (sqlite, postgres, fetched via carne std init)

Full API reference with examples: https://openpeeps.github.io/carne/

Roadmap

  • JSC runtime: console/process/require/timers CLI
  • Package management (carne pkg, manifests)
  • Format std libs (yaml, toml, ical, env, plist, bson, csv, xml, vcard, feed)
  • std/sql, std/crypto, std/path, std/colors
  • std/css, std/diff, std/gettext, std/mimetype, std/benchmark, std/qr, std/svg
  • std/http (async client + server, tuning opts, method helpers) + top-level promise unwrap in runCode
  • std/ws (async + sync client, server, binary/ping/protocol, wss:// client)
  • std/http workers (cluster-style threads, process.isWorker)
  • std/uuid (v1-v8 generation, parse/inspect, RFC namespace constants)
  • std/db (async + sync driver, fluent builder, models, migrations; sqlite + postgres)
  • std/archive (tar/zip/rar creation + extraction, gz/lz4/bz2/brotli; in-memory and file APIs)
  • Lazy startup (deferred event loop, per-run TLS, cached spec data)
  • Benchmark suite + results
  • Top-level await in scripts (currently needs an async IIFE)
  • std/crypto: X25519 exchange, RSA/ECDSA, AES-GCM
  • std/gettext .mo file catalogs, std/svg stringify (std/qr decode deferred)
  • exportClass in the module DSL
  • Public package registry (getcarne/carnepkgs)
  • carne pkg publish (fork + PR flow, .tokens auth)
  • Beyond macOS (Linux via JavaScriptCoreGTK 4.1)

Benchmarks

Kinda useless JS bench suite (bench/js, via hyperfine --warmup 2 --min-runs 3, macOS, bench/run.sh reproduces; node v22.22.1, bun 1.4.3):

Benchmark carne node bun
fib_recursive 42.4 ms ± 0.5 ms 85.1 ms ± 1.1 ms 45.5 ms ± 1.0 ms
nested_loops 9.3 ms ± 0.4 ms 36.3 ms ± 0.7 ms 11.9 ms ± 0.4 ms
prime_sieve 9.2 ms ± 0.3 ms 35.0 ms ± 0.5 ms 11.7 ms ± 0.3 ms
string_concat 9.4 ms ± 0.3 ms 34.5 ms ± 0.5 ms 11.7 ms ± 0.7 ms
tail_recursive 9.7 ms ± 0.3 ms CRASHED 11.8 ms ± 0.3 ms
range_sum 38.4 ms ± 0.4 ms 43.8 ms ± 0.4 ms 19.6 ms ± 0.3 ms
collatz 51.1 ms ± 0.4 ms 69.5 ms ± 0.7 ms 53.4 ms ± 2.3 ms
array_sum 14.6 ms ± 0.5 ms 40.7 ms ± 0.9 ms 16.8 ms ± 0.3 ms
bubble_sort 11.8 ms ± 0.3 ms 36.7 ms ± 0.4 ms 14.5 ms ± 0.3 ms
object_access 11.3 ms ± 0.3 ms 36.9 ms ± 0.4 ms 14.0 ms ± 0.3 ms
float_math 12.9 ms ± 0.3 ms 39.1 ms ± 1.0 ms 16.5 ms ± 0.4 ms
call_overhead 10.4 ms ± 0.2 ms 35.5 ms ± 0.4 ms 12.5 ms ± 0.3 ms
fizzbuzz_count 43.8 ms ± 0.4 ms 64.8 ms ± 0.6 ms 38.3 ms ± 0.4 ms

A cold hello.js run costs carne ~8.5 ms, so everything near that floor is startup-dominated (JSC context + stdlib install), not compute. Node crashes tail_recursive (no proper tail calls: stack overflow at 10k frames); carne inherits JSC's tail-call support, like bun.

HTTP hello-world (wrk)

Throughput bench (bench/http-hello, bench/http-hello/run.sh reproduces; wrk 4.2.0, wrk -t4 -c100 -d10s after a 2s warmup, port 3000, macOS, node v22.22.1, bun 1.4.4). Each server answers 200 text/plain "hello world" to every request; carne-workers is the same server with {workers: 4} (bench/http-hello/server.carne.workers.js):

Runtime Requests/sec Avg latency Max RSS
carne 91330.44 1.15ms 10.9 MB
carne-workers 144029.68 739.70us 28.3 MB
node 38576.69 2.71ms 61.5 MB
bun 86878.46 1.15ms 31.1 MB

Bodies are byte-identical (11 bytes); headers differ per runtime, so Transfer/sec is not directly comparable. Max RSS is sampled via ps during the measured run (includes shared libraries).

❤ Contributions & Support

🎩 License

MIT license. Made by Humans from OpenPeeps.
Copyright OpenPeeps & Contributors — All rights reserved.

About

Yeah, another JavaScript runtime! Written in Nim language

Topics

Resources

Stars

16 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

Generated from openpeeps/pistachio