resourcexjs 0.4.0 → 0.7.0

package/README.md

@@ -1,213 +1,287 @@
 # resourcexjs
 
-Agent Resource Protocol (ARP) for AI Agents.
+ResourceX - Resource management protocol for AI Agents. Like npm for AI resources.
 
 ## Installation
 
 ```bash
-npm install resourcexjs
+npm install resourcexjs @resourcexjs/registry
 # or
-bun add resourcexjs
+bun add resourcexjs @resourcexjs/registry
 ```
 
 ## Quick Start
 
 ```typescript
-import { createResourceX } from "resourcexjs";
+import { createRegistry } from "@resourcexjs/registry";
+import { createRXM, createRXC, parseRXL } from "resourcexjs";
+
+// Create registry
+const registry = createRegistry();
+
+// Prepare a resource
+const manifest = createRXM({
+  domain: "localhost",
+  name: "my-prompt",
+  type: "text",
+  version: "1.0.0",
+});
+
+const rxr = {
+  locator: parseRXL(manifest.toLocator()),
+  manifest,
+  content: createRXC("You are a helpful assistant."),
+};
 
-const rx = createResourceX();
+// Link to local registry
+await registry.link(rxr);
 
-// Resolve a remote text resource
-const resource = await rx.resolve("arp:text:https://example.com/file.txt");
-// Or use shorthand (@ is default)
-const resource = await rx.resolve("@text:https://example.com/file.txt");
+// Resolve resource
+const resource = await registry.resolve("localhost/my-prompt.text@1.0.0");
+console.log(await resource.content.text());
+```
+
+## API
 
-console.log(resource.type); // "text"
-console.log(resource.content); // file content as string
-console.log(resource.meta); // { url, semantic, transport, ... }
+### RXL - Resource Locator
 
-// Deposit a local text resource
-await rx.deposit("@text:file://./data/config.txt", "hello world");
+Parse resource locator strings. Format: `[domain/path/]name[.type][@version]`
 
-// Binary resources
-await rx.deposit("@binary:file://./data/image.png", imageBuffer);
-const binary = await rx.resolve("@binary:file://./data/image.png");
-console.log(binary.content); // Buffer
+```typescript
+import { parseRXL } from "resourcexjs";
 
-// Check if resource exists
-const exists = await rx.exists("@text:file://./data/config.txt");
+const rxl = parseRXL("deepractice.ai/sean/assistant.prompt@1.0.0");
 
-// Delete a resource
-await rx.delete("@text:file://./data/config.txt");
+rxl.domain; // "deepractice.ai"
+rxl.path; // "sean"
+rxl.name; // "assistant"
+rxl.type; // "prompt"
+rxl.version; // "1.0.0"
+rxl.toString(); // reconstructs the locator
 ```
 
-### URL Prefix
+### RXM - Resource Manifest
 
-- `arp:` - Standard prefix (always supported)
-- `@` - Shorthand alias (default, configurable via `alias` config)
+Create resource metadata:
 
-## ARP URL Format
+```typescript
+import { createRXM } from "resourcexjs";
+
+const manifest = createRXM({
+  domain: "deepractice.ai",
+  path: "sean", // optional
+  name: "assistant",
+  type: "prompt",
+  version: "1.0.0",
+});
 
+manifest.toLocator(); // → "deepractice.ai/sean/assistant.prompt@1.0.0"
+manifest.toJSON(); // → plain object
 ```
-arp:{semantic}:{transport}://{location}
+
+### RXC - Resource Content
+
+Stream-based content (consumed once, like fetch Response):
+
+```typescript
+import { createRXC, loadRXC } from "resourcexjs";
+
+// Create from memory
+const content = createRXC("Hello");
+const content = createRXC(Buffer.from([1, 2, 3]));
+const content = createRXC(readableStream);
+
+// Load from file or URL
+const content = await loadRXC("./file.txt");
+const content = await loadRXC("https://example.com/data.txt");
+
+// Consume (can only use one method)
+await content.text(); // → string
+await content.buffer(); // → Buffer
+await content.json<T>(); // → T
+content.stream; // → ReadableStream<Uint8Array>
 ```
 
-- **semantic**: What the resource is (e.g., `text`, `binary`)
-- **transport**: How to access it (e.g., `https`, `http`, `file`)
-- **location**: Where to find it
+### RXR - Resource
 
-Examples:
+Complete resource object (pure interface):
 
-- `arp:text:https://example.com/readme.txt`
-- `arp:binary:file:///path/to/image.png`
-- `arp:text:file://./local/file.txt`
+```typescript
+interface RXR {
+  locator: RXL;
+  manifest: RXM;
+  content: RXC;
+}
 
-## Resource Definition
+// Create from literals
+const rxr: RXR = { locator, manifest, content };
+```
 
-Define custom resources as shortcuts for commonly used ARP URLs:
+### Registry
+
+Resource storage and retrieval (from `@resourcexjs/registry`):
 
 ```typescript
-import { createResourceX } from "resourcexjs";
-import { join } from "path";
-import { homedir } from "os";
-
-const rx = createResourceX({
-  resources: [
-    {
-      name: "logs",
-      semantic: "text",
-      transport: "file",
-      basePath: join(homedir(), ".myapp", "logs"),
-    },
-    {
-      name: "cache",
-      semantic: "binary",
-      transport: "file",
-      basePath: join(homedir(), ".myapp", "cache"),
-    },
-  ],
+import { createRegistry } from "@resourcexjs/registry";
+
+const registry = createRegistry({
+  path: "~/.resourcex", // optional
+  types: [customType], // optional, defaults to built-in types
 });
 
-// Use resource URL
-await rx.deposit("logs://app.log", "log entry");
-await rx.deposit("cache://data.bin", buffer);
+// Link (local development/cache)
+await registry.link(rxr);
+
+// Resolve (local-first, then remote)
+const rxr = await registry.resolve("deepractice.ai/assistant.prompt@1.0.0");
+
+// Check existence
+const exists = await registry.exists("localhost/test.text@1.0.0");
 
-// Equivalent to full ARP URL
-await rx.deposit("arp:text:file://~/.myapp/logs/app.log", "log entry");
+// Delete
+await registry.delete("localhost/test.text@1.0.0");
+
+// Search (TODO)
+const results = await registry.search("assistant");
 ```
 
-## API
+### Resource Types
+
+Built-in types:
 
-### `createResourceX(config?)`
+| Type     | Aliases          | Description    |
+| -------- | ---------------- | -------------- |
+| `text`   | txt, plaintext   | Plain text     |
+| `json`   | config, manifest | JSON content   |
+| `binary` | bin, blob, raw   | Binary content |
 
-Create a ResourceX instance.
+Define custom types:
 
 ```typescript
-const rx = createResourceX({
-  timeout: 5000, // request timeout in ms
-  transports: [], // custom transport handlers
-  semantics: [], // custom semantic handlers
-  resources: [], // resource definitions
+import { defineResourceType } from "resourcexjs";
+
+defineResourceType({
+  name: "prompt",
+  aliases: ["deepractice-prompt"],
+  description: "AI Prompt template",
+  serializer: {
+    serialize: async (rxr) => Buffer.from(await rxr.content.text()),
+    deserialize: async (data, manifest) => ({
+      locator: parseRXL(manifest.toLocator()),
+      manifest,
+      content: createRXC(data.toString()),
+    }),
+  },
+  resolver: {
+    resolve: async (rxr) => ({
+      template: await rxr.content.text(),
+      // ... custom methods
+    }),
+  },
 });
 ```
 
-### `rx.resolve(url)`
+### TypeHandlerChain
 
-Resolve an ARP or Resource URL and return the resource.
+Responsibility chain for type handling (used internally):
 
 ```typescript
-const resource = await rx.resolve("arp:text:https://example.com/file.txt");
-// Returns: { type, content, meta }
+import { createTypeHandlerChain, builtinTypes } from "resourcexjs";
 
-const resource = await rx.resolve("myresource://file.txt");
-// Also works with resource URLs
+const chain = createTypeHandlerChain(builtinTypes);
+
+chain.serialize(rxr); // → Buffer
+chain.deserialize(buffer, manifest); // → RXR
+chain.resolve<T>(rxr); // → T (usable object)
 ```
 
-### `rx.deposit(url, data)`
+## ARP - Low-level I/O
 
-Deposit data to an ARP or Resource URL.
+For direct file/network operations:
 
 ```typescript
-await rx.deposit("arp:text:file://./data/config.txt", "content");
-await rx.deposit("arp:binary:file://./data/image.png", buffer);
-```
+import { createARP } from "resourcexjs/arp";
 
-### `rx.exists(url)`
+const arp = createARP(); // Defaults include file, http, https, text, binary
 
-Check if a resource exists.
+// Parse URL
+const arl = arp.parse("arp:text:file://./config.txt");
 
-```typescript
-const exists = await rx.exists("arp:text:file://./data/config.txt");
-// Returns: boolean
-```
+// Read
+const resource = await arl.resolve();
+console.log(resource.content); // string
 
-### `rx.delete(url)`
+// Write
+await arl.deposit("hello world");
 
-Delete a resource.
-
-```typescript
-await rx.delete("arp:text:file://./data/config.txt");
+// Operations
+await arl.exists(); // → boolean
+await arl.delete();
 ```
 
-### `rx.parse(url)`
+## Exports
 
-Parse a URL without fetching.
+### Main Package (`resourcexjs`)
 
 ```typescript
-const parsed = rx.parse("arp:text:https://example.com/file.txt");
-// Returns: { semantic: "text", transport: "https", location: "example.com/file.txt" }
+// Errors
+export { ResourceXError, LocatorError, ManifestError, ContentError, ResourceTypeError };
 
-const parsed = rx.parse("myresource://file.txt");
-// Also works with resource URLs (expanded to full location)
-```
+// RXL (Locator)
+export { parseRXL };
+export type { RXL };
 
-## Built-in Semantic Types
+// RXM (Manifest)
+export { createRXM };
+export type { RXM, ManifestData };
 
-| Type     | Content  | Description                    |
-| -------- | -------- | ------------------------------ |
-| `text`   | `string` | Plain text with UTF-8 encoding |
-| `binary` | `Buffer` | Raw binary, no transformation  |
+// RXC (Content)
+export { createRXC, loadRXC };
+export type { RXC };
 
-## Resource Object
+// RXR (Resource)
+export type { RXR, ResourceType, ResourceSerializer, ResourceResolver };
 
-```typescript
-interface Resource {
-  type: string; // semantic type (e.g., "text", "binary")
-  content: unknown; // parsed content (string for text, Buffer for binary)
-  meta: {
-    url: string; // original URL
-    semantic: string; // semantic type
-    transport: string; // transport protocol
-    location: string; // resource location
-    size: number; // content size in bytes
-    encoding?: string; // content encoding (for text)
-    resolvedAt: string; // ISO timestamp
-  };
-}
+// ResourceType
+export { defineResourceType, getResourceType, clearResourceTypes };
+export { textType, jsonType, binaryType, builtinTypes };
+export { TypeHandlerChain, createTypeHandlerChain };
 ```
 
-## Error Handling
-
-All errors extend `ResourceXError`:
+### Registry Package (`@resourcexjs/registry`)
 
 ```typescript
-import { createResourceX, ResourceXError } from "resourcexjs";
+export { createRegistry, ARPRegistry };
+export { RegistryError };
+export type { Registry, RegistryConfig };
+```
 
-const rx = createResourceX();
+### ARP Package (`resourcexjs/arp`)
 
-try {
-  await rx.resolve("arp:text:https://example.com/file.txt");
-} catch (error) {
-  if (error instanceof ResourceXError) {
-    console.error("ResourceX error:", error.message);
-  }
-}
+```typescript
+export { createARP, ARP, type ARPConfig };
+export { ARPError, ParseError, TransportError, SemanticError };
+export type { ARI, ARL };
+export { fileTransport, httpTransport, httpsTransport };
+export { textSemantic, binarySemantic };
 ```
 
-For fine-grained error handling, import specific error types from `@resourcexjs/core`:
+## Error Hierarchy
 
-```typescript
-import { ParseError, TransportError, SemanticError } from "@resourcexjs/core";
+```
+Error
+└── ResourceXError
+    ├── LocatorError (RXL parsing)
+    ├── ManifestError (RXM validation)
+    ├── ContentError (RXC consumption)
+    └── ResourceTypeError (Type registration)
+
+└── RegistryError (Registry operations)
+
+└── ARPError
+    ├── ParseError (URL parsing)
+    ├── TransportError (Transport not found)
+    └── SemanticError (Semantic not found)
 ```
 
 ## License

package/dist/arp.d.ts

@@ -0,0 +1 @@
+export * from "@resourcexjs/arp";