# @archildata/native

> **Not recommended for most use cases.** This package exposes Archil's *low-level* filesystem protocol (inodes, delegations, byte-level reads and writes, permission checks) to Node.js via a native addon. It's useful if you're building a custom client runtime on top of Archil, but it's the wrong tool for most people.
>
> - If you want to **create, list, inspect, or run commands against** an Archil disk from code or a CLI, use [`disk`](https://www.npmjs.com/package/disk) — `disk exec <id> <cmd>` is the serverless way to run commands against a disk without talking to any filesystem protocol at all.
> - If you want to **mount an Archil disk as a local filesystem**, install the [`archil`](https://archil.com) CLI — it uses the OS kernel's FUSE layer so you can read and write files with standard tools.
>
> This package is still published for the small number of integrations that genuinely need raw protocol access from Node.

Low-level Node.js client for [Archil](https://archil.com) — speaks the Archil filesystem protocol directly (no mount, no FUSE, no kernel). Implemented as a napi-rs native addon so the hot path is Rust, surfaced through a JavaScript API.

## Install

```bash
npm install @archildata/native
```

Ships prebuilt binaries for **Linux** (x64, arm64, glibc) and **macOS** (arm64). Other platforms aren't supported.

## Usage

```typescript
import { ArchilClient } from '@archildata/native';

const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/my-disk',
  authToken: '<your-mount-token>',
});

// Look up a file by name in the root directory (inode 1)
const entry = await client.lookupInode(1, 'config.json');

// Read its contents
const data = await client.readInode(entry.inodeId, 0, entry.attributes.size);
console.log(data.toString());

await client.close();
```

### Writing files

Archil uses delegations for writes. Check out before writing, check in when done:

```typescript
await client.checkout(inodeId);
await client.writeData(inodeId, 0, Buffer.from('new contents'));
await client.sync();
await client.checkin(inodeId);
```

### Listing directories

```typescript
const handle = await client.openDirectory(1);
const page = await client.readDirectory(1, handle, 100);
for (const entry of page.entries) {
  console.log(`${entry.name} (${entry.inodeType})`);
}
client.closeDirectory(1, handle);
```

For large directories, pass `page.nextCursor` back into `readDirectory`. When `nextCursor` is `undefined`, you've seen everything.

### Creating files and directories

```typescript
const dir = await client.create(1, 'mydir', {
  inodeType: 'Directory',
  uid: 1000, gid: 1000, mode: 0o755,
});

const file = await client.create(dir.inodeId, 'data.txt', {
  inodeType: 'File',
  uid: 1000, gid: 1000, mode: 0o644,
});
```

### Renaming and deleting

```typescript
await client.rename(parentInodeId, 'old.txt', parentInodeId, 'new.txt');
await client.unlink(parentInodeId, 'new.txt');
```

Always `await client.close()` when done — this flushes pending writes and releases delegations.

## Support

Questions, feature requests, or issues? Reach us at **support@archil.com**.
