@resourcexjs/type

Type system for ResourceX with sandbox-compatible execution.

Installation

``bash
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.

$3

- 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

$3

`typescript
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"]
`

$3

`typescript
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
`

$3

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

`typescript
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):

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

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

$3

`typescript
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

$3

Type registry managing type lookup and registration.

#### Static Methods

##### TypeHandlerChain.create(): TypeHandlerChain

Create a new TypeHandlerChain instance with builtin types.

`typescript
const chain = TypeHandlerChain.create();
`

#### Instance Methods

##### register(type: BundledType): void

Register a custom type.

Throws: ResourceTypeError if type name or alias already exists.

`typescript
chain.register(promptType);
`

##### canHandle(typeName: string): boolean

Check if a type is supported.

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

##### getHandler(typeName: string): BundledType

Get handler for a type.

Throws: ResourceTypeError if type not supported.

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

##### getHandlerOrUndefined(typeName: string): BundledType | undefined

Get handler or undefined if not found.

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

##### getSupportedTypes(): string[]

Get all supported type names (including aliases).

`typescript
const types = chain.getSupportedTypes();
`

##### clear(): void

Clear all registered types (for testing).

`typescript
chain.clear();
`

$3

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

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

Types

$3

Pre-bundled resource type ready for execution:

`typescript
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
}
`

$3

Context passed to resolver in sandbox:

`typescript
interface ResolveContext {
manifest: {
domain: string;
path?: string;
name: string;
type: string;
version: string;
};
files: Record;
}
`

$3

Result object returned after resolution:

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

$3

Interface for defining custom types (before bundling):

`typescript
interface ResourceType {
name: string;
aliases?: string[];
description: string;
resolver: ResourceResolver;
}
`

$3

Sandbox isolation levels (configured at Registry level):

`typescript
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

$3

prompt.type.ts:

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

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

$3

tool.type.ts:

`typescript
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

`typescript
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

`typescript
// 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