Runtime Manual/Reference & Specs/Modules, Package Management & Testing

Modules, Package Management & Testing

Dual-cache module resolution, seamless npm interoperability, and Jest-compatible built-in test runner

1. Dual-Cache Module Resolution (4.6M ops/s)

In large-scale microservice applications, hundreds of modules are evaluated during startup.

Traditional Resolution Inefficiencies

When executing require() or import, traditional Node.js engines perform repeated, expensive syscalls:

  1. Crawling parent directory hierarchies to locate node_modules.
  2. Parsing package.json for exports and main entries.
  3. Probing multiple extensions (.js, .json, .node).
  4. Making dozens of stat or access calls per module, degrading cold start times.

Amber Stat-Bypass Architecture

Amber utilizes a two-tier in-memory normalized cache:

code
         require('lodash') or import ... from './utils'
                            │
                            ▼
      +─────────────────────────────────────────────+
      |  L1: Normalized Path Cache                  |
      |  - Instant hash lookup for resolved paths   |
      +─────────────────────────────────────────────+
                            │ Cache Miss
                            ▼
      +─────────────────────────────────────────────+
      |  L2: Resolved Specifier Cache               |
      |  - Avoids re-parsing package.json exports   |
      |  - Bypasses filesystem stat syscalls        |
      +─────────────────────────────────────────────+

In official benchmarks, Amber achieves 4,601,226 ops/s in module resolution—4.1x faster than Node.js (1.12M ops/s) and ahead of Bun (3.88M ops/s).

2. ESM & CommonJS Interoperability

Amber natively supports seamless interop between ECMAScript Modules (ESM) and CommonJS (CJS):

code
// 1. Standard ESM imports
import { readFileSync } from 'node:fs';
import { Tensor } from 'amber:ai';

// 2. CommonJS require alongside ESM
const path = require('node:path');

// 3. Dynamic import expressions
if (process.env.LOAD_OPTIONAL) {
  const mod = await import('./optional-module.js');
  mod.init();
}

// 4. Module metadata
console.log('Module URL:', import.meta.url);
console.log('Directory name:', __dirname);
console.log('File name:', __filename);

Module Scheme Prefixes

  • node:*: Explicitly imports Node.js compatible core modules (recommended).
  • amber:*: Imports Amber native built-ins (e.g. amber:ai for tensors and inference).
  • Relative / Absolute paths: ./, ../, / for local disk modules with automatic .ts and .tsx extension resolution.

3. Built-In Package Management

Amber includes lightweight package management compatible with the npm registry, requiring no separate npm or pnpm installation:

code
# 1. Initialize a new project with package.json
amber init my-app

# 2. Add production dependency
amber add lodash@4.17.21

# 3. Add development dependency
amber add --dev @types/node

# 4. Install dependencies in CI with strict integrity
amber install --frozen-lockfile

# 5. Remove unused dependencies
amber prune

4. Built-in Test Framework (amber test)

Amber provides a zero-dependency test runner compatible with Jest and Vitest conventions:

Writing Tests

Create a test file such as math.test.ts:

code
// math.test.ts
import { describe, it, test, expect } from 'amber:test';

describe('Arithmetic & Logic', () => {
  it('adds numbers correctly', () => {
    expect(1 + 1).toBe(2);
    expect([1, 2, 3]).toHaveLength(3);
    expect({ name: 'amberjs' }).toEqual({ name: 'amberjs' });
  });

  test('handles async resolutions', async () => {
    const data = await Promise.resolve('ready');
    expect(data).toBe('ready');
  });

  test('asserts thrown errors', () => {
    expect(() => {
      throw new Error('Invalid input');
    }).toThrow('Invalid input');
  });
});

Running Tests

code
# Run all test files (*.test.js, *.test.ts, *.spec.ts)
$ amber test

# Filter tests by matching pattern
$ amber test -t "async"

# Run tests in parallel across workers
$ amber test --parallel

# Terminate immediately on first failure
$ amber test --bail

# Watch mode
$ amber test -w

Execution report:

code
 PASS  tests/math.test.ts (12 ms)
  Arithmetic & Logic
    ✓ adds numbers correctly (1 ms)
    ✓ handles async resolutions (2 ms)
    ✓ asserts thrown errors (0 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        0.018s
PreviousFull API Reference