@resourcexjs/type

Type system for ResourceX with sandbox-compatible execution.

Installation

bun add @resourcexjs/type

Overview

The @resourcexjs/type package provides the type system for ResourceX, managing how different resource types are resolved and executed in sandboxed environments.

Key Concepts

• BundledType: Pre-bundled resource type ready for sandbox execution
• TypeHandlerChain: Type registry managing type lookup and registration
• ResolveContext: Serializable context passed to resolvers in sandbox
• Builtin Types: Text, JSON, and Binary types are included by default

Usage

Using TypeHandlerChain

import { TypeHandlerChain } from "@resourcexjs/type";

// Create a new chain (builtin types included)
const chain = TypeHandlerChain.create();

// Check if type is supported
chain.canHandle("text"); // true
chain.canHandle("json"); // true
chain.canHandle("binary"); // true

// Builtin aliases
chain.canHandle("txt"); // true (alias for text)
chain.canHandle("config"); // true (alias for json)
chain.canHandle("bin"); // true (alias for binary)

// Get handler
const handler = chain.getHandler("text");
console.log(handler.name); // "text"
console.log(handler.code); // bundled resolver code

// Get all supported types
const types = chain.getSupportedTypes();
// ["text", "txt", "plaintext", "json", "config", "manifest", "binary", "bin", "blob", "raw"]

Registering Custom Types

import { TypeHandlerChain, bundleResourceType } from "@resourcexjs/type";

// Bundle a resource type from source file
const promptType = await bundleResourceType("./prompt.type.ts");

// Register with chain
const chain = TypeHandlerChain.create();
chain.register(promptType);

// Now the chain can handle the new type
chain.canHandle("prompt"); // true

Bundling Resource Types

Resource types must be bundled before registration. The bundler converts a .type.ts source file into a BundledType with executable code:

import { bundleResourceType } from "@resourcexjs/type";

// Bundle from source file
const myType = await bundleResourceType("./my-resource.type.ts");
// Returns: { name, aliases, description, schema, code }

Source file format (my-resource.type.ts):

export default {
  name: "prompt",
  aliases: ["deepractice-prompt"],
  description: "AI Prompt template",

  async resolve(ctx) {
    // ctx.manifest - resource metadata
    // ctx.files - extracted files as Record<string, Uint8Array>
    const content = new TextDecoder().decode(ctx.files["content"]);
    return content;
  },
};

Accessing Builtin Types Directly

import { textType, jsonType, binaryType, builtinTypes } from "@resourcexjs/type";

// Individual types
console.log(textType.name); // "text"
console.log(jsonType.aliases); // ["config", "manifest"]
console.log(binaryType.description); // "Binary content"

// All builtin types as array
for (const type of builtinTypes) {
  console.log(type.name);
}

API Reference

TypeHandlerChain

Type registry managing type lookup and registration.

Static Methods

TypeHandlerChain.create(): TypeHandlerChain

Create a new TypeHandlerChain instance with builtin types.

const chain = TypeHandlerChain.create();

Instance Methods

register(type: BundledType): void

Register a custom type.

Throws: ResourceTypeError if type name or alias already exists.

chain.register(promptType);

canHandle(typeName: string): boolean

Check if a type is supported.

chain.canHandle("text"); // true
chain.canHandle("unknown"); // false

getHandler(typeName: string): BundledType

Get handler for a type.

Throws: ResourceTypeError if type not supported.

const handler = chain.getHandler("text");

getHandlerOrUndefined(typeName: string): BundledType | undefined

Get handler or undefined if not found.

const handler = chain.getHandlerOrUndefined("unknown"); // undefined

getSupportedTypes(): string[]

Get all supported type names (including aliases).

const types = chain.getSupportedTypes();

clear(): void

Clear all registered types (for testing).

chain.clear();

bundleResourceType(sourcePath, basePath?)

Bundle a resource type from a source file.

Parameters:

• sourcePath: string - Path to the .type.ts file
• basePath?: string - Base path for resolving relative paths (defaults to cwd)

Returns: Promise<BundledType>

const myType = await bundleResourceType("./my-resource.type.ts");

Types

BundledType

Pre-bundled resource type ready for execution:

interface BundledType {
  name: string; // Type name (e.g., "text", "json")
  aliases?: string[]; // Alternative names
  description: string; // Human-readable description
  schema?: JSONSchema; // JSON Schema for resolver arguments
  code: string; // Bundled resolver code
}

ResolveContext

Context passed to resolver in sandbox:

interface ResolveContext {
  manifest: {
    domain: string;
    path?: string;
    name: string;
    type: string;
    version: string;
  };
  files: Record<string, Uint8Array>;
}

ResolvedResource

Result object returned after resolution:

interface ResolvedResource<TArgs = void, TResult = unknown> {
  resource: unknown; // Original RXR object
  execute: (args?: TArgs) => TResult | Promise<TResult>;
  schema: TArgs extends void ? undefined : JSONSchema;
}

ResourceType

Interface for defining custom types (before bundling):

interface ResourceType<TArgs = void, TResult = unknown> {
  name: string;
  aliases?: string[];
  description: string;
  resolver: ResourceResolver<TArgs, TResult>;
}

IsolatorType

Sandbox isolation levels (configured at Registry level):

type IsolatorType = "none" | "srt" | "cloudflare" | "e2b";

• "none": No isolation, fastest (~10ms), for development
• "srt": OS-level isolation (~50ms), secure local dev
• "cloudflare": Container isolation (~100ms), local Docker or edge
• "e2b": MicroVM isolation (~150ms), production (planned)

Builtin Types

Three builtin types are included by default:

| Type | Aliases | Resolves to | Description | | -------- | -------------------- | ------------ | ------------------ | | text | txt, plaintext | string | Plain text content | | json | config, manifest | unknown | JSON content | | binary | bin, blob, raw | Uint8Array | Binary content |

Creating Custom Types

Example: Simple Type (No Arguments)

prompt.type.ts:

export default {
  name: "prompt",
  aliases: ["deepractice-prompt"],
  description: "AI Prompt template",

  async resolve(ctx) {
    const content = new TextDecoder().decode(ctx.files["content"]);
    return content;
  },
};

Example: Type with Schema

tool.type.ts:

export default {
  name: "tool",
  description: "Executable tool with arguments",
  schema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search keyword" },
      limit: { type: "number", description: "Max results", default: 10 },
    },
    required: ["query"],
  },

  async resolve(ctx) {
    // The schema is used by the executor to validate/render UI
    // The resolver returns the tool definition
    const code = new TextDecoder().decode(ctx.files["content"]);
    return { code, manifest: ctx.manifest };
  },
};

Error Handling

import { ResourceTypeError } from "@resourcexjs/type";

try {
  chain.getHandler("unknown");
} catch (error) {
  if (error instanceof ResourceTypeError) {
    console.error("Type error:", error.message);
    // "Unsupported resource type: unknown"
  }
}

Exports

// Types
export type {
  ResourceType,
  ResourceResolver,
  ResolvedResource,
  ResolveContext,
  JSONSchema,
  JSONSchemaProperty,
  BundledType,
  IsolatorType,
} from "@resourcexjs/type";

// Classes and Functions
export { TypeHandlerChain } from "@resourcexjs/type";
export { bundleResourceType } from "@resourcexjs/type";
export { ResourceTypeError } from "@resourcexjs/type";

// Builtin Types
export { textType, jsonType, binaryType, builtinTypes } from "@resourcexjs/type";

License

Apache-2.0