Foundation Layer

The Foundation layer (Layer 0) provides the lowest-level building blocks for the entire .do ecosystem. These types form the bedrock upon which all higher-level abstractions are built - from file system operations to authentication, from shell execution to cryptographic verification.

Why Foundation Matters

Every sophisticated platform rests on infrastructure primitives. The Foundation layer standardizes these primitives with TypeScript types that ensure:

Type Safety - Catch errors at compile time, not runtime
Consistency - Common patterns across all infrastructure operations
Interoperability - Types that work across Node.js, Workers, and browsers
Documentation - Self-documenting interfaces that teach usage

Module Overview

Module	Domain	Description
Filesystem	`fsx`	POSIX-style file operations, streaming, multi-tenant isolation
Git	`gitx`	Repository operations, commits, branches, diffs
RPC	`rpc.do`	JSON-RPC 2.0, transports, typed proxies
Auth	`oauth.do`	OAuth 2.0, API keys, RBAC, sessions
Bash	`bashx`	Shell execution, safety analysis, AST parsing
Attestation	`npx`	Cryptographic execution verification
CLI	`cli.do`	Terminal UI, formatting, REPL types
Compression	-	Streaming compression utilities

Installation

npm install @dotdo/types

Importing Foundation Types

All foundation types are available from the main package or the foundation subpath:

// Import from main package
import type { FileSystemCapability, GitRepository, RPCClient } from '@dotdo/types'

// Or import from foundation subpath
import type { FileInfo, DirectoryEntry } from '@dotdo/types/foundation'

The Infrastructure Pattern

Foundation types follow a consistent pattern:

Capability Interfaces - Define what operations are available
Option Types - Configure operation behavior
Result Types - Describe operation outcomes
Error Types - Provide structured error handling

// Capability: What can I do?
interface FileSystemCapability {
  readFile(path: string, options?: ReadFileOptions): Promise<string | Uint8Array>
  writeFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>
  // ...
}

// Options: How should I do it?
interface ReadFileOptions {
  encoding?: FileEncoding
  signal?: AbortSignal
}

// Result: What happened?
interface FileInfo {
  path: string
  size: number
  mtime: Timestamp
  // ...
}

// Error: What went wrong?
interface FileSystemError extends Error {
  code: FileSystemErrorCode
  path: string
  operation: string
}

Cross-Cutting Concerns

Foundation types handle several cross-cutting concerns:

Streaming

Web Streams API compatibility across all I/O operations:

import type { ReadStream, WriteStream } from '@dotdo/types/foundation'

const readStream: ReadStream = fs.createReadStream('/data/file.bin')
const writeStream: WriteStream = fs.createWriteStream('/data/output.bin')

await readStream.pipeTo(writeStream)

Error Handling

Structured errors with POSIX-style error codes:

import { isFileSystemError } from '@dotdo/types/foundation'

try {
  await fs.readFile('/nonexistent')
} catch (error) {
  if (isFileSystemError(error)) {
    switch (error.code) {
      case 'ENOENT': console.log('File not found')
      case 'EACCES': console.log('Permission denied')
    }
  }
}

Async Operations

All long-running operations return Promises with optional AbortSignal support:

const controller = new AbortController()

// Start operation
const promise = fs.readFile('/data/large-file.bin', {
  signal: controller.signal
})

// Cancel if needed
controller.abort()

Primitives - Semantic concepts (Noun, Verb, Thing, Action, Event)
Platform - Higher-level platform services built on Foundation
Workers - Execution contexts that use Foundation types

Foundation Layer

On this page