uncontainerizable

https://www.npmjs.com/package/uncontainerizable
Admin
A process lifecycle supervisor for programs that cannot run in traditional containers, providing...
Tokens:10,012
Snippets:145
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Quick Start

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=versions

A basic example demonstrating how to use the `App` class to spawn and manage a process, and how to shut it down gracefully.

```APIDOC
## Quick Start

Here's a simple example of how to use `uncontainerizable` to manage an application:

```javascript
import { App, defaultAdapters } from "uncontainerizable";

// Initialize an App instance with a unique prefix for namespacing.
const app = new App("com.example.my-supervisor");

// Spawn a 'chromium' process and contain it.
const container = await app.contain("chromium", {
  args: ["--user-data-dir=/tmp/browser-profile"],
  identity: "browser-main", // Ensures only one instance with this identity runs.
  adapters: [...defaultAdapters], // Use default lifecycle hooks.
});

// Later, when you want to shut down the process cleanly:
const result = await container.destroy();

if (result.errors.length > 0) {
  console.warn("Teardown surfaced recoverable errors:", result.errors);
}

console.log(`Process exited at stage: ${result.quit.exitedAtStage}`);
```

**Note:** If you call `app.contain` again with the same `identity`, the previous instance will be preempted (killed) before the new one starts. Omit `identity` to disable this preemption behavior.
```

--------------------------------

### Quick Start

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

A basic example demonstrating how to use the `App` class to spawn and manage a process with uncontainerizable.

```APIDOC
## Quick Start

Here's a simple example of how to use `uncontainerizable` to manage an application:

```javascript
import { App, defaultAdapters } from "uncontainerizable";

// Initialize an App instance with a unique prefix for namespacing.
const app = new App("com.example.my-supervisor");

// Spawn a 'chromium' process, providing arguments and an identity for singleton enforcement.
const container = await app.contain("chromium", {
  args: ["--user-data-dir=/tmp/browser-profile"],
  identity: "browser-main", // This identity will preempt any existing 'browser-main' instance.
  adapters: [...defaultAdapters], // Use default lifecycle adapters.
});

// ... Later, when you want to shut down the managed process cleanly:
const result = await container.destroy();

if (result.errors.length > 0) {
  console.warn("Teardown surfaced recoverable errors:", result.errors);
}

console.log(`Process exited at stage: ${result.quit.exitedAtStage}`);
```

If you call `app.contain` again with the same `identity`, the previous instance will be terminated before the new one starts. Omit `identity` to disable this preemption behavior.
```

--------------------------------

### Installation

Source: https://www.npmjs.com/package/uncontainerizable

Instructions on how to install the uncontainerizable npm package.

```APIDOC
## Install

`npm i uncontainerizable`
```

--------------------------------

### Installation

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

Instructions on how to install the uncontainerizable package using npm, pnpm, or yarn.

```APIDOC
## Installation

Install the `uncontainerizable` package using your preferred package manager:

```bash
npm install uncontainerizable
# or
pnpm add uncontainerizable
# or
yarn add uncontainerizable
```

The package includes prebuilt Node.js binaries, so no native toolchain is required at install time. Node.js version 24 or higher is recommended. The package is distributed as ESM only.
```

--------------------------------

### Install uncontainerizable

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

Commands to install the package using common Node.js package managers.

```bash
npm install uncontainerizable
# or
pnpm add uncontainerizable
# or
yarn add uncontainerizable
```

--------------------------------

### Get Rust Core Version

Source: https://www.npmjs.com/package/uncontainerizable

Retrieve the version string of the underlying Rust core. This is useful for logging and support purposes.

```javascript
import { coreVersion } from "uncontainerizable";

console.log(coreVersion());
```

--------------------------------

### Initialize and manage a contained process

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

Demonstrates creating an App instance, spawning a process with identity-based singleton enforcement, and performing a clean teardown.

```javascript
import { App, defaultAdapters } from "uncontainerizable";

const app = new App("com.example.my-supervisor");

const container = await app.contain("chromium", {
  args: ["--user-data-dir=/tmp/browser-profile"],
  identity: "browser-main", // preempts any previous "browser-main"
  adapters: [...defaultAdapters],
});

// ... later, when you want to shut it down cleanly:
const result = await container.destroy();

if (result.errors.length > 0) {
  console.warn("teardown surfaced recoverable errors:", result.errors);
}

console.log(`exited at ${result.quit.exitedAtStage}`);
```

--------------------------------

### new App(prefix)

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=dependents

Creates a namespaced handle for spawning contained processes.

```APIDOC
## new App(prefix)

### Description
Creates a namespaced handle for spawning contained processes. The prefix namespaces identity strings to prevent collisions.

### Parameters
#### Path Parameters
- **prefix** (string) - Required - Conventionally reverse-DNS (e.g., "com.example.my-supervisor").

### Errors
- Throws `INVALID_IDENTITY` if `prefix` contains characters outside `[A-Za-z0-9._:-]`.
```

--------------------------------

### App Initialization

Source: https://www.npmjs.com/package/uncontainerizable

Initialize a new App instance, which acts as a namespaced handle for spawning contained processes. The prefix namespaces identity strings to prevent collisions.

```APIDOC
## new App(prefix)

### Description
Namespaced handle for spawning contained processes. The `prefix` (conventionally reverse-DNS, e.g. `"com.example.my-supervisor"`) namespaces identity strings so unrelated libraries can't collide.
Throws `INVALID_IDENTITY` if `prefix` contains characters outside `[A-Za-z0-9._:-]`.
```

--------------------------------

### API Documentation

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=code

Detailed documentation for the `App` class and its methods, including constructors, spawning processes, and lifecycle management.

```APIDOC
## API

### `new App(prefix)`

**Description:** Creates a namespaced handle for spawning contained processes. The `prefix` (conventionally reverse-DNS, e.g., `"com.example.my-supervisor"`) namespaces identity strings, preventing collisions between unrelated libraries.

**Parameters:**
- **prefix** (string) - Required - A string used to namespace process identities.

**Throws:**
- `INVALID_IDENTITY` if the `prefix` contains characters outside the allowed set `[A-Za-z0-9._:-]`.

### `app.contain(command, options?) → Promise<Container>`

**Description:** Spawns a new process and manages its lifecycle.

**Parameters:**
- **command** (string) - Required - The command to execute.
- **options** (object) - Optional - Configuration options for the contained process.
  - **args** (string[]) - Optional - Command-line arguments for the process.
  - **env** (Record<string, string>) - Optional - Environment variable overrides.
  - **cwd** (string) - Optional - The working directory for the process.
  - **identity** (string) - Optional - Enables singleton enforcement; if provided, any existing process with the same identity will be killed before the new one starts.
  - **adapters** (Array<Adapter>) - Optional - An array of lifecycle hooks for the process.
  - **darwinTagArgv0** (boolean) - Optional (macOS only) - Set to `false` if the managed program incorrectly reads `argv[0]`.

**Returns:**
- `Promise<Container>` - A promise that resolves to a `Container` object representing the spawned process.

### `container.quit(options?) → Promise<QuitResult>`

**Description:** Initiates the staged quit ladder for the contained process without releasing platform resources. This is useful when you want to wait for the process to drain but keep the container handle active.

**Parameters:**
- **options** (object) - Optional - Options for the quit operation.

**Returns:**
- `Promise<QuitResult>` - A promise that resolves with the result of the quit operation.

### `container.destroy(options?) → Promise<DestroyResult>`

**Description:** Runs the staged quit ladder and releases all associated platform resources. This method always resolves successfully; any recoverable errors encountered during the process are aggregated in the `result.errors` array and do not cause the promise to reject.

**Parameters:**
- **options** (object) - Optional - Options for the destroy operation.

**Returns:**
- `Promise<DestroyResult>` - A promise that resolves with the result of the destroy operation, including any errors.

### `coreVersion() → string`

**Description:** Returns the version string of the underlying Rust core library. This is useful for logging and support purposes.

**Returns:**
- `string` - The version string of the Rust core.
```

--------------------------------

### API Documentation

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=versions

Detailed documentation for the `App` class and its methods, including constructors, spawning processes, and lifecycle management.

```APIDOC
## API

### `new App(prefix)`

**Description:** Creates a namespaced handle for spawning contained processes. The `prefix` (conventionally reverse-DNS, e.g., `"com.example.my-supervisor"`) namespaces identity strings, preventing collisions between unrelated libraries.

**Parameters:**
- **prefix** (string) - Required - A string used to namespace process identities.

**Throws:**
- `INVALID_IDENTITY` if the `prefix` contains characters outside the allowed set `[A-Za-z0-9._:-]`.

### `app.contain(command, options?) → Promise<Container>`

**Description:** Spawns a new process and manages its lifecycle.

**Parameters:**
- **command** (string) - Required - The command to execute.
- **options** (object) - Optional - Configuration options for the contained process.
  - **args** (string[]) - Optional - Command-line arguments for the process.
  - **env** (Record<string, string>) - Optional - Environment variable overrides.
  - **cwd** (string) - Optional - The working directory for the process.
  - **identity** (string) - Optional - Enables singleton enforcement; if provided, any existing process with the same identity will be killed before the new one starts.
  - **adapters** (Adapter[]) - Optional - An array of per-app lifecycle hooks.
  - **darwinTagArgv0** (boolean) - Optional - macOS only. Set to `false` if the managed program incorrectly reads `argv[0]`.

**Returns:**
- `Promise<Container>` - A promise that resolves to a `Container` object representing the spawned process.

### `container.quit(options?) → Promise<QuitResult>`

**Description:** Initiates the staged quit ladder for the contained process without releasing platform resources. This is useful when you want to wait for the process to drain but keep the container handle active.

**Parameters:**
- **options** (object) - Optional - Options for the quit operation.

**Returns:**
- `Promise<QuitResult>` - A promise that resolves with the result of the quit operation.

### `container.destroy(options?) → Promise<DestroyResult>`

**Description:** Runs the quit ladder and releases all associated platform resources. This method always resolves successfully; any recoverable errors encountered during the process are aggregated in the `result.errors` array and do not cause the promise to reject.

**Parameters:**
- **options** (object) - Optional - Options for the destroy operation.

**Returns:**
- `Promise<DestroyResult>` - A promise that resolves with the result of the destroy operation, including any errors.

### `coreVersion() → string`

**Description:** Returns the version string of the underlying Rust core library. This is useful for logging and support purposes.

**Returns:**
- `string` - The version string of the Rust core.
```

--------------------------------

### coreVersion()

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=dependents

Returns the Rust core version string.

```APIDOC
## coreVersion()

### Description
Returns the Rust core's version string.

### Response
- **string** - The version string.
```

--------------------------------

### app.contain(command, options)

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=dependents

Spawns a contained process with specified options.

```APIDOC
## app.contain(command, options)

### Description
Spawns a contained process. If an identity is provided, it enforces singleton behavior by killing any prior instance.

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute.
- **options** (object) - Optional
  - **args** (string[]) - Optional - Command-line arguments.
  - **env** (Record) - Optional - Environment overrides.
  - **cwd** (string) - Optional - Working directory.
  - **identity** (string) - Optional - Enables singleton enforcement.
  - **adapters** (Adapter[]) - Optional - Per-app lifecycle hooks.
  - **darwinTagArgv0** (boolean) - Optional - macOS only; set false if the managed program misreads argv[0].

### Response
- **Container** (Promise) - Returns a container instance.
```

--------------------------------

### Custom Adapter Implementation

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=dependents

Defines the structure and lifecycle hooks for creating a custom adapter in uncontainerizable.

```APIDOC
## Custom Adapter Interface

### Description
An adapter is an object that implements the `Adapter` interface. It allows for custom logic to be executed during the application teardown process via various lifecycle hooks.

### Adapter Structure
- **name** (string) - Required - Unique identifier for the adapter.
- **matches** (function) - Required - Predicate function to determine if the adapter applies to a given probe.
- **beforeQuit** (function) - Optional - Hook executed before the teardown ladder starts.
- **beforeStage** (function) - Optional - Hook executed before a specific teardown stage.
- **afterStage** (function) - Optional - Hook executed after a specific teardown stage.
- **afterQuit** (function) - Optional - Hook executed after the teardown ladder ends.
- **clearCrashState** (function) - Optional - Hook executed only after a terminal-stage teardown.

### Implementation Example
```typescript
import type { Adapter } from "uncontainerizable";

const logger: Adapter = {
  name: "logger",
  matches: () => true,
  beforeStage(probe, stageName) {
    console.log(`[${probe.pid}] entering stage ${stageName}`);
  },
  afterStage(_probe, result) {
    if (result.exited) {
      console.log(`drained at ${result.stageName}`);
    }
  },
};
```
```

--------------------------------

### Built-in Adapters

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=code

Information about the pre-defined adapters available in the uncontainerizable package, their purposes, and how to import them.

```APIDOC
## Built-in Adapters

Adapters match by probe (bundle ID, executable path, platform). Their `clearCrashState` hook runs after a terminal-stage teardown to suppress restart dialogs.

| Adapter       | Purpose                                                                   |
|---------------|---------------------------------------------------------------------------|
| `appkit`      | Deletes AppKit's "Saved Application State" directory on macOS.            |
| `crashReporter` | Clears per-app entries from macOS's user-level CrashReporter archive.       |
| `chromium`    | Matches Chrome/Chromium/Brave/Edge. Crash-state cleanup is stubbed.       |
| `firefox`     | Matches Firefox. Crash-state cleanup is stubbed.                          |

Import individually or as a bundle:
```javascript
import {
  appkit,
  chromium,
  crashReporter,
  defaultAdapters,
  firefox,
} from "uncontainerizable";
```
```

--------------------------------

### Custom Adapters

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=code

Details on creating and using custom adapters with the uncontainerizable package, including the available hooks and their functionalities.

```APIDOC
## Custom Adapters

An adapter is any object matching the `Adapter` shape. Every hook except `name` and `matches` is optional; unimplemented hooks are skipped. Hooks may be sync or async — the wrapper normalizes both forms before crossing the napi boundary.

```javascript
import type { Adapter } from "uncontainerizable";

const logger: Adapter = {
  name: "logger",
  matches: () => true,
  beforeStage(probe, stageName) {
    console.log(`[${probe.pid}] entering stage ${stageName}`);
  },
  afterStage(_probe, result) {
    if (result.exited) {
      console.log(`drained at ${result.stageName}`);
    }
  },
};
```

Hook surface:
  * `beforeQuit(probe)` — before the ladder starts.
  * `beforeStage(probe, stageName)` / `afterStage(probe, result)` — around each stage.
  * `afterQuit(probe, result)` — after the ladder ends, terminal or not.
  * `clearCrashState(probe)` — only after a terminal-stage teardown.

> [!TIP] Adapter hooks are **advisory** : errors are collected into `QuitResult.adapterErrors` and never abort the quit ladder. A misbehaving adapter cannot prevent teardown.
```

--------------------------------

### Importing Adapters

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

Import built-in adapters individually or as a default bundle from the package.

```typescript
import {
  appkit,
  chromium,
  crashReporter,
  defaultAdapters,
  firefox,
} from "uncontainerizable";
```

--------------------------------

### Adapter Interface and Hook Lifecycle

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=versions

Defines the structure of an adapter and the available hooks for managing application lifecycle stages.

```APIDOC
## Adapter Interface

### Description
An adapter is an object that implements the `Adapter` interface to hook into the application teardown process. Hooks can be synchronous or asynchronous.

### Hook Surface
- **name** (string) - Required - Unique identifier for the adapter.
- **matches** (function) - Required - Predicate function to determine if the adapter applies to the current probe.
- **beforeQuit(probe)** - Optional - Executed before the teardown ladder starts.
- **beforeStage(probe, stageName)** - Optional - Executed before each teardown stage.
- **afterStage(probe, result)** - Optional - Executed after each teardown stage.
- **afterQuit(probe, result)** - Optional - Executed after the ladder ends.
- **clearCrashState(probe)** - Optional - Executed only after a terminal-stage teardown to suppress restart dialogs.

### Implementation Example
```typescript
import type { Adapter } from "uncontainerizable";

const logger: Adapter = {
  name: "logger",
  matches: () => true,
  beforeStage(probe, stageName) {
    console.log(`[${probe.pid}] entering stage ${stageName}`);
  },
  afterStage(_probe, result) {
    if (result.exited) {
      console.log(`drained at ${result.stageName}`);
    }
  },
};
```
```

--------------------------------

### container.destroy(options)

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=dependents

Runs the quit ladder and releases platform resources.

```APIDOC
## container.destroy(options)

### Description
Runs the quit ladder and releases platform resources. Always resolves; recoverable errors appear in the result object.

### Response
- **DestroyResult** (Promise) - Contains errors and quit status.
```

--------------------------------

### API Documentation

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

Detailed documentation for the core classes and methods provided by the uncontainerizable package.

```APIDOC
## API

### `new App(prefix)`

**Description:** Creates a namespaced handle for spawning contained processes. The `prefix` (conventionally reverse-DNS, e.g., `"com.example.my-supervisor"`) ensures that identity strings are namespaced, preventing collisions between unrelated libraries.

**Parameters:**
- **prefix** (string) - A unique identifier for namespacing.

**Throws:**
- `INVALID_IDENTITY`: If the `prefix` contains characters outside the allowed set `[A-Za-z0-9._:-]`.

### `app.contain(command, options?) → Promise<Container>`

**Description:** Spawns a new process managed by the container.

**Parameters:**
- **command** (string) - The command to execute.
- **options** (object, optional) - Configuration options for the contained process.
  - **args** (string[]) - Command-line arguments for the process.
  - **env** (Record<string, string>) - Environment variable overrides.
  - **cwd** (string) - The working directory for the process.
  - **identity** (string) - If provided, ensures only one instance with this identity runs at a time. A previous instance will be preempted.
  - **adapters** (Adapter[]) - An array of lifecycle hooks for managing the process.
  - **darwinTagArgv0** (boolean, macOS only) - Set to `false` if the managed program incorrectly reads `argv[0]`.

**Returns:**
- `Promise<Container>` - A promise that resolves to a `Container` object representing the spawned process.

### `container.quit(options?) → Promise<QuitResult>`

**Description:** Initiates the staged quit ladder for the managed process without releasing platform resources. This is useful for waiting for the process to drain while keeping the container handle active.

**Returns:**
- `Promise<QuitResult>` - A promise that resolves with the result of the quit operation.

### `container.destroy(options?) → Promise<DestroyResult>`

**Description:** Executes the quit ladder and releases all associated platform resources. This method always resolves successfully; any recoverable errors encountered during the process are aggregated in the `result.errors` array and do not cause the promise to reject.

**Returns:**
- `Promise<DestroyResult>` - A promise that resolves with the result of the destroy operation, including any errors.

### `coreVersion() → string`

**Description:** Returns the version string of the underlying Rust core library. This is useful for logging and support purposes.

**Returns:**
- `string` - The version string of the Rust core.
```

--------------------------------

### Contain Process

Source: https://www.npmjs.com/package/uncontainerizable

Spawns a contained process with specified options. If an `identity` is provided, any existing process with that identity will be preempted (killed) before the new one is launched.

```APIDOC
## app.contain(command, options?)

### Description
Spawns a contained process. Options:

### Method
`app.contain

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute.
- **options** (object) - Optional - Configuration for the contained process.
  - **args** (string[]) - Optional - Command-line arguments.
  - **env** (Record<string, string>) - Optional - Environment overrides.
  - **cwd** (string) - Optional - Working directory.
  - **identity** (string) - Optional - Enables singleton enforcement; prior instance is killed first.
  - **adapters** (Adapter[]) - Optional - Per-app lifecycle hooks.
  - **darwinTagArgv0** (boolean) - Optional - macOS only; set `false` if the managed program misreads argv[0].
```

--------------------------------

### container.quit(options)

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=dependents

Runs the staged quit ladder without releasing platform resources.

```APIDOC
## container.quit(options)

### Description
Runs the staged quit ladder without releasing platform resources. Use when you want to wait for the process to drain but keep the container handle alive.

### Response
- **QuitResult** (Promise) - Returns the result of the quit operation.
```

--------------------------------

### Core Version

Source: https://www.npmjs.com/package/uncontainerizable

Retrieves the version string of the underlying Rust core, which can be useful for logging and support purposes.

```APIDOC
## coreVersion()

### Description
Returns the Rust core's version string — handy for logging and support.

### Method
`coreVersion`
```

--------------------------------

### Defining a Custom Adapter

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

Implement the Adapter interface to create custom hooks. Hooks are advisory and errors are collected in QuitResult.adapterErrors.

```typescript
import type { Adapter } from "uncontainerizable";

const logger: Adapter = {
  name: "logger",
  matches: () => true,
  beforeStage(probe, stageName) {
    console.log(`[${probe.pid}] entering stage ${stageName}`);
  },
  afterStage(_probe, result) {
    if (result.exited) {
      console.log(`drained at ${result.stageName}`);
    }
  },
};
```

--------------------------------

### Container Destroy

Source: https://www.npmjs.com/package/uncontainerizable

Runs the quit ladder and releases all platform resources associated with the container. This method always resolves, with any recoverable errors reported in the `result.errors` array.

```APIDOC
## container.destroy(options?)

### Description
Runs the quit ladder and releases platform resources. Always resolves: recoverable errors appear in `result.errors`, never as a thrown exception.

### Method
`container.destroy`

### Parameters
#### Query Parameters
- **options** (object) - Optional - Options for destroying the container.
```

--------------------------------

### Container Quit

Source: https://www.npmjs.com/package/uncontainerizable

Initiates the staged quit ladder for a containerized process without releasing platform resources. This allows the process to drain gracefully while keeping the container handle active.

```APIDOC
## container.quit(options?)

### Description
Runs the staged quit ladder without releasing platform resources. Use when you want to wait for the process to drain but keep the container handle alive.

### Method
`container.quit`

### Parameters
#### Query Parameters
- **options** (object) - Optional - Options for quitting.
```

--------------------------------

### Exported TypeScript Types

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=readme

Access public types directly from the package root.

```typescript
import type {
  Adapter,
  ContainOptions,
  Container,
  DestroyOptions,
  DestroyResult,
  Probe,
  QuitOptions,
  QuitResult,
  StageResult,
  SupportedPlatform,
} from "uncontainerizable";
```

--------------------------------

### TypeScript Types

Source: https://www.npmjs.com/package/uncontainerizable?activeTab=code

Lists the public TypeScript types exported by the uncontainerizable package for use in your projects.

```APIDOC
## TypeScript

All public types are exported from the package root:

```typescript
import type {
  Adapter,
  ContainOptions,
  Container,
  DestroyOptions,
  DestroyResult,
  Probe,
  QuitOptions,
  QuitResult,
  StageResult,
  SupportedPlatform,
} from "uncontainerizable";
```
```
Tokens:
Raw