Capabilities System

Bridges automatically detect which optional operations they support. The capabilities system allows you to check which operations are available at runtime and provides type-safe access to optional operations.

Overview

The optionalCapabilities property on a bridge instance is a map indicating which optional operations are available:

interface HasOptionalCapabilityMap {
  write: boolean;
  mkdir: boolean;
  rm: boolean;
}

Each bridge automatically detects its capabilities based on which operations are implemented in the setup function. For example, the HTTP bridge is read-only and has all capabilities set to false, while the Node.js bridge supports all operations and has all capabilities set to true.

Checking Capabilities

Use the hasCapability function to check if a bridge supports an operation:

import { hasCapability } from "@ucdjs/fs-bridge";

if (hasCapability(bridge, "write")) {
  // TypeScript now knows bridge.write exists
  await bridge.write("file.txt", "content");
}

// Check multiple capabilities
if (hasCapability(bridge, ["write", "mkdir"])) {
  await bridge.write("file.txt", "content");
  await bridge.mkdir("directory");
}

The hasCapability function acts as a TypeScript type guard, narrowing the bridge type to include the checked capabilities.

Asserting Capabilities

Use assertCapability to throw an error if a capability is not available:

import { assertCapability } from "@ucdjs/fs-bridge";

assertCapability(bridge, "write");
// TypeScript now knows bridge.write exists
await bridge.write("file.txt", "content");

If the bridge doesn't support the requested capability, assertCapability throws a BridgeUnsupportedOperation error.

Type Safety

The capabilities system is fully type-safe. TypeScript will:

Infer optional capabilities based on what operations are implemented
Narrow types when using hasCapability or assertCapability
Provide autocomplete for all operations after capability checks

Example: Working with Read-Only Bridges

import HTTPFileSystemBridge from "@ucdjs/fs-bridge/bridges/http";

const bridge = HTTPFileSystemBridge({
  baseUrl: new URL("https://api.ucdjs.dev/api/v1/files")
});

// Check if write is supported before attempting
if (hasCapability(bridge, "write")) {
  await bridge.write("file.txt", "content");
} else {
  console.log("This bridge is read-only");
}

// Or assert and handle the error
try {
  assertCapability(bridge, "write");
  await bridge.write("file.txt", "content");
} catch (error) {
  if (error instanceof BridgeUnsupportedOperation) {
    console.log(`Bridge doesn't support ${error.capability}`);
  }
}

Best Practices

Always check capabilities: Before calling optional operations, use hasCapability or assertCapability to ensure the operation is supported.
Use type guards: The hasCapability function provides type narrowing, allowing TypeScript to know that optional operations exist after the check.
Handle unsupported operations gracefully: Read-only bridges (like HTTP) don't support write operations. Always check capabilities before attempting optional operations.

Capabilities