@resourcexjs/core 0.9.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @resourcexjs/core
 
-Core types and implementations for ResourceX.
+Core data structures for ResourceX.
 
 > **Note**: For most use cases, use the main [`resourcexjs`](https://www.npmjs.com/package/resourcexjs) package. This package is for advanced usage.
 
@@ -14,14 +14,12 @@ bun add @resourcexjs/core
 
 ## What's Inside
 
-Core building blocks for ResourceX:
+Core building blocks - pure data structures:
 
-- **RXL** (Locator) - Parse locator strings
-- **RXM** (Manifest) - Create resource metadata
+- **RXL** (Locator) - Resource locator string parser
+- **RXM** (Manifest) - Resource metadata
 - **RXC** (Content) - Stream-based content
 - **RXR** (Resource) - Complete resource type
-- **ResourceType** - Type system with serializer & resolver
-- **TypeHandlerChain** - Responsibility chain for type handling
 - **Errors** - Error hierarchy
 
 ## API
@@ -43,6 +41,13 @@ rxl.version; // "1.0.0"
 rxl.toString(); // "deepractice.ai/sean/assistant.prompt@1.0.0"
 ```
 
+**Minimal locator:**
+
+```typescript
+parseRXL("name.text@1.0.0");
+// → domain: "localhost", path: undefined, name: "name", type: "text", version: "1.0.0"
+```
+
 ### RXM - Resource Manifest
 
 Create and validate resource metadata:
@@ -56,40 +61,54 @@ const manifest = createRXM({
   name: "assistant",
   type: "prompt",
   version: "1.0.0",
+  description: "Optional description", // optional
+  tags: ["optional", "tags"], // optional
 });
 
 manifest.toLocator(); // → "deepractice.ai/sean/assistant.prompt@1.0.0"
 manifest.toJSON(); // → plain object
 ```
 
-Required fields: domain, name, type, version
+**Required fields**: `name`, `type`, `version`
+
+**Optional fields**: `domain` (default: "localhost"), `path`, `description`, `tags`
 
 ### RXC - Resource Content
 
-Stream-based content (can only be consumed once, like fetch Response):
+Archive-based content (internally tar.gz), supports single or multi-file resources:
 
 ```typescript
-import { createRXC, loadRXC } from "@resourcexjs/core";
-
-// Create from memory
-const content = createRXC("Hello, World!");
-const content = createRXC(Buffer.from([1, 2, 3]));
-const content = createRXC(readableStream);
-
-// Load from file or URL (async)
-const content = await loadRXC("./file.txt");
-const content = await loadRXC("https://example.com/data.txt");
-
-// Consume (choose one, can only use once)
-const text = await content.text(); // → string
-const buffer = await content.buffer(); // → Buffer
-const json = await content.json<T>(); // → T
-const stream = content.stream; // → ReadableStream<Uint8Array>
+import { createRXC } from "@resourcexjs/core";
+
+// Single file
+const content = await createRXC({ content: "Hello, World!" });
+
+// Multiple files
+const content = await createRXC({
+  "index.ts": "export default 1",
+  "styles.css": "body {}",
+});
+
+// Nested directories
+const content = await createRXC({
+  "src/index.ts": "main code",
+  "src/utils/helper.ts": "helper code",
+});
+
+// From existing tar.gz archive (for deserialization)
+const content = await createRXC({ archive: tarGzBuffer });
+
+// Read files
+const buffer = await content.file("content"); // → Buffer
+const buffer = await content.file("src/index.ts"); // → Buffer
+const files = await content.files(); // → Map<string, Buffer>
+const archiveBuffer = await content.buffer(); // → raw tar.gz Buffer
+const stream = content.stream; // → ReadableStream (tar.gz)
 ```
 
 ### RXR - Resource
 
-Complete resource object (pure interface, no factory):
+Complete resource object (pure interface):
 
 ```typescript
 import type { RXR } from "@resourcexjs/core";
@@ -101,156 +120,149 @@ interface RXR {
 }
 
 // Create from literals
-const rxr: RXR = {
-  locator: parseRXL("localhost/test.text@1.0.0"),
-  manifest: createRXM({ domain: "localhost", name: "test", type: "text", version: "1.0.0" }),
-  content: createRXC("content"),
-};
+const rxr: RXR = { locator, manifest, content };
 ```
 
-### Resource Types
+RXR is a pure DTO (Data Transfer Object) - no factory function needed.
 
-Built-in types:
+## Error Handling
 
 ```typescript
-import { textType, jsonType, binaryType, builtinTypes } from "@resourcexjs/core";
+import { ResourceXError, LocatorError, ManifestError, ContentError } from "@resourcexjs/core";
 
-console.log(textType.name); // "text"
-console.log(textType.aliases); // ["txt", "plaintext"]
-console.log(jsonType.aliases); // ["config", "manifest"]
-console.log(binaryType.aliases); // ["bin", "blob", "raw"]
-```
+try {
+  parseRXL("invalid-locator");
+} catch (error) {
+  if (error instanceof LocatorError) {
+    console.error("Invalid locator format");
+  }
+}
 
-Define custom types:
+try {
+  createRXM({ name: "test" }); // Missing required fields
+} catch (error) {
+  if (error instanceof ManifestError) {
+    console.error("Invalid manifest");
+  }
+}
 
-```typescript
-import { defineResourceType } from "@resourcexjs/core";
-
-defineResourceType({
-  name: "prompt",
-  aliases: ["deepractice-prompt"],
-  description: "AI Prompt template",
-  serializer: {
-    async serialize(rxr: RXR): Promise<Buffer> {
-      // Convert RXR to Buffer for storage
-      const text = await rxr.content.text();
-      return Buffer.from(JSON.stringify({ template: text }));
-    },
-    async deserialize(data: Buffer, manifest: RXM): Promise<RXR> {
-      // Convert Buffer back to RXR
-      const obj = JSON.parse(data.toString());
-      return {
-        locator: parseRXL(manifest.toLocator()),
-        manifest,
-        content: createRXC(obj.template),
-      };
-    },
-  },
-  resolver: {
-    async resolve(rxr: RXR): Promise<PromptTemplate> {
-      // Convert RXR to usable object
-      return {
-        template: await rxr.content.text(),
-        compile: (vars) => {
-          /* ... */
-        },
-      };
-    },
-  },
-});
+try {
+  await content.text();
+  await content.text(); // Second consumption
+} catch (error) {
+  if (error instanceof ContentError) {
+    console.error("Content already consumed");
+  }
+}
 ```
 
-Query registered types:
-
-```typescript
-import { getResourceType, clearResourceTypes } from "@resourcexjs/core";
-
-const type = getResourceType("text");
-const type = getResourceType("txt"); // Works with aliases
+### Error Hierarchy
 
-clearResourceTypes(); // For testing
+```
+ResourceXError (base)
+├── LocatorError
+├── ManifestError
+└── ContentError
 ```
 
-### TypeHandlerChain
+## Examples
 
-Responsibility chain for type handling (used internally by Registry):
+### Complete Resource Creation
 
 ```typescript
-import { createTypeHandlerChain, builtinTypes } from "@resourcexjs/core";
+import { parseRXL, createRXM, createRXC } from "@resourcexjs/core";
+import type { RXR } from "@resourcexjs/core";
 
-// Create with initial types
-const chain = createTypeHandlerChain(builtinTypes);
+// Create manifest
+const manifest = createRXM({
+  domain: "deepractice.ai",
+  name: "assistant",
+  type: "prompt",
+  version: "1.0.0",
+});
 
-// Or start empty
-const chain = createTypeHandlerChain();
-chain.register(customType);
-chain.registerAll([type1, type2]);
+// Create locator from manifest
+const locator = parseRXL(manifest.toLocator());
 
-// Use the chain
-chain.canHandle("text"); // → boolean
-chain.getHandler("txt"); // → ResourceType (via alias)
+// Create content (single file)
+const content = await createRXC({ content: "You are a helpful assistant." });
 
-await chain.serialize(rxr); // → Buffer
-await chain.deserialize(buffer, manifest); // → RXR
-await chain.resolve<T>(rxr); // → T (usable object)
+// Assemble RXR
+const rxr: RXR = {
+  locator,
+  manifest,
+  content,
+};
 ```
 
-## Error Handling
+### Multi-file Resource
 
 ```typescript
-import {
-  ResourceXError,
-  LocatorError,
-  ManifestError,
-  ContentError,
-  ResourceTypeError,
-} from "@resourcexjs/core";
+import { createRXC } from "@resourcexjs/core";
 
-try {
-  const rxl = parseRXL("invalid");
-} catch (error) {
-  if (error instanceof LocatorError) {
-    console.error("Invalid locator:", error.message);
-  }
+// Create multi-file content
+const content = await createRXC({
+  "prompt.md": "# System Prompt\nYou are...",
+  "config.json": '{"temperature": 0.7}',
+});
+
+// Read individual files
+const promptBuffer = await content.file("prompt.md");
+const configBuffer = await content.file("config.json");
+
+// Read all files
+const allFiles = await content.files();
+for (const [path, buffer] of allFiles) {
+  console.log(path, buffer.toString());
 }
 ```
 
-Error hierarchy:
+### Manifest Serialization
 
-```
-Error
-└── ResourceXError
-    ├── LocatorError (RXL parsing)
-    ├── ManifestError (RXM validation)
-    ├── ContentError (RXC consumption)
-    └── ResourceTypeError (Type not found/duplicate)
+```typescript
+const manifest = createRXM({
+  name: "assistant",
+  type: "prompt",
+  version: "1.0.0",
+});
+
+// To JSON (for storage)
+const json = manifest.toJSON();
+/*
+{
+  "domain": "localhost",
+  "name": "assistant",
+  "type": "prompt",
+  "version": "1.0.0"
+}
+*/
+
+// To locator string
+const locator = manifest.toLocator();
+// "localhost/assistant.prompt@1.0.0"
 ```
 
-## Complete Exports
+## Related Packages
 
-```typescript
-// Errors
-export { ResourceXError, LocatorError, ManifestError, ContentError, ResourceTypeError };
+This package provides only data structures. For full functionality:
 
-// RXL (Locator)
-export { parseRXL };
-export type { RXL };
+- **[@resourcexjs/type](../type)** - Type system and handlers
+- **[@resourcexjs/loader](../loader)** - Resource loading
+- **[@resourcexjs/registry](../registry)** - Storage and retrieval
+- **[@resourcexjs/arp](../arp)** - Low-level I/O
+- **[resourcexjs](../resourcex)** - Main package (all-in-one)
 
-// RXM (Manifest)
-export { createRXM };
-export type { RXM, ManifestData };
+## Type Safety
 
-// RXC (Content)
-export { createRXC, loadRXC };
-export type { RXC };
+All types are fully typed with TypeScript:
 
-// RXR (Resource)
-export type { RXR, ResourceType, ResourceSerializer, ResourceResolver };
+```typescript
+import type { RXL, RXM, RXC, RXR } from "@resourcexjs/core";
 
-// ResourceType
-export { defineResourceType, getResourceType, clearResourceTypes };
-export { textType, jsonType, binaryType, builtinTypes };
-export { TypeHandlerChain, createTypeHandlerChain };
+const locator: RXL = parseRXL("...");
+const manifest: RXM = createRXM({ ... });
+const content: RXC = createRXC("...");
+const resource: RXR = { locator, manifest, content };
 ```
 
 ## License

package/dist/index.d.ts

@@ -14,9 +14,6 @@ declare class ManifestError extends ResourceXError {
 declare class ContentError extends ResourceXError {
 	constructor(message: string);
 }
-declare class ResourceTypeError extends ResourceXError {
-	constructor(message: string);
-}
 /**
 * RXL - ResourceX Locator
 *
@@ -62,26 +59,28 @@ declare function createRXM(data: ManifestData): RXM;
 /**
 * RXC - ResourceX Content
 *
-* Represents resource content as a stream.
+* Archive-based content container using tar.gz format internally.
+* Provides unified file access API for both single and multi-file resources.
 */
 interface RXC {
-	/** Content as a readable stream */
+	/** Content as a readable stream (tar.gz format) */
 	readonly stream: ReadableStream<Uint8Array>;
-	/** Read content as text */
-	text(): Promise<string>;
-	/** Read content as Buffer */
+	/** Get raw archive buffer (tar.gz format) */
 	buffer(): Promise<Buffer>;
-	/** Read content as JSON */
-	json<T>(): Promise<T>;
+	/** Read a specific file from the archive */
+	file(path: string): Promise<Buffer>;
+	/** Read all files from the archive */
+	files(): Promise<Map<string, Buffer>>;
 }
 /**
-* Create RXC from string, Buffer, or ReadableStream.
-*/
-declare function createRXC(data: string | Buffer | ReadableStream<Uint8Array>): RXC;
-/**
-* Load RXC from file path or URL.
+* Input type for createRXC.
+* - Files record: { 'path/to/file': content }
+* - Archive: { archive: tarGzBuffer }
 */
-declare function loadRXC(source: string): Promise<RXC>;
+type RXCInput = Record<string, Buffer | Uint8Array | string> | {
+	archive: Buffer
+};
+declare function createRXC(input: RXCInput): Promise<RXC>;
 /**
 * RXR (ResourceX Resource) - Complete resource object.
 * A pure data transfer object combining locator, manifest, and content.
@@ -91,208 +90,4 @@ interface RXR {
 	manifest: RXM;
 	content: RXC;
 }
-/**
-* ResourceSerializer - Handles RXR serialization/deserialization for storage.
-*/
-interface ResourceSerializer {
-	/**
-	* Serialize RXR to storage format.
-	*/
-	serialize(rxr: RXR): Promise<Buffer>;
-	/**
-	* Deserialize storage data to RXR.
-	*/
-	deserialize(data: Buffer, manifest: RXM): Promise<RXR>;
-}
-/**
-* ResourceResolver - Transforms RXR into usable object.
-*/
-interface ResourceResolver<T = unknown> {
-	/**
-	* Resolve RXR content into a usable object.
-	*/
-	resolve(rxr: RXR): Promise<T>;
-}
-/**
-* ResourceType - Defines how a resource type is handled.
-*/
-interface ResourceType<T = unknown> {
-	/**
-	* Type name (e.g., "text", "json", "binary").
-	*/
-	name: string;
-	/**
-	* Alternative names for this type (e.g., ["txt", "plaintext"]).
-	*/
-	aliases?: string[];
-	/**
-	* Human-readable description.
-	*/
-	description: string;
-	/**
-	* Serializer for storage operations.
-	*/
-	serializer: ResourceSerializer;
-	/**
-	* Resolver to transform RXR into usable object.
-	*/
-	resolver: ResourceResolver<T>;
-}
-/**
-* ResourceLoader - Strategy interface for loading resources from different sources.
-*/
-interface ResourceLoader {
-	/**
-	* Check if this loader can handle the given source.
-	*
-	* @param source - Source path or identifier
-	* @returns true if this loader can handle the source
-	*/
-	canLoad(source: string): boolean | Promise<boolean>;
-	/**
-	* Load a resource from the given source.
-	*
-	* @param source - Source path or identifier
-	* @returns Complete RXR object
-	* @throws ResourceXError if loading fails
-	*/
-	load(source: string): Promise<RXR>;
-}
-/**
-* Define and register a resource type.
-*
-* @throws ResourceTypeError if type is already registered
-*/
-declare function defineResourceType<T>(config: ResourceType<T>): ResourceType<T>;
-/**
-* Get a registered resource type by name.
-*
-* @returns ResourceType or undefined if not found
-*/
-declare function getResourceType<T = unknown>(name: string): ResourceType<T> | undefined;
-/**
-* Clear all registered resource types (for testing).
-*/
-declare function clearResourceTypes(): void;
-/**
-* Text resource type
-*/
-declare const textType: ResourceType<string>;
-/**
-* JSON resource type
-*/
-declare const jsonType: ResourceType<unknown>;
-/**
-* Binary resource type
-*/
-declare const binaryType: ResourceType<Buffer>;
-/**
-* All built-in types
-*/
-declare const builtinTypes: ResourceType[];
-/**
-* TypeHandlerChain - Responsibility chain for resource type handling.
-* Manages type registration and delegates serialization/deserialization.
-*/
-declare class TypeHandlerChain {
-	private handlers;
-	/**
-	* Register a resource type handler.
-	* Registers both the type name and its aliases.
-	*/
-	register(type: ResourceType): void;
-	/**
-	* Register multiple type handlers.
-	*/
-	registerAll(types: ResourceType[]): void;
-	/**
-	* Check if a type is supported.
-	*/
-	canHandle(typeName: string): boolean;
-	/**
-	* Get handler for a type.
-	*/
-	getHandler(typeName: string): ResourceType | undefined;
-	/**
-	* Serialize RXR content using the appropriate type handler.
-	*/
-	serialize(rxr: RXR): Promise<Buffer>;
-	/**
-	* Deserialize content into RXR using the appropriate type handler.
-	*/
-	deserialize(data: Buffer, manifest: RXM): Promise<RXR>;
-	/**
-	* Resolve RXR content into usable object using the appropriate type handler.
-	*/
-	resolve<T = unknown>(rxr: RXR): Promise<T>;
-}
-/**
-* Create a new TypeHandlerChain with optional initial types.
-*/
-declare function createTypeHandlerChain(types?: ResourceType[]): TypeHandlerChain;
-/**
-* Default ResourceLoader implementation for loading resources from folders.
-*
-* Expected folder structure:
-* ```
-* folder/
-* ├── resource.json    # Resource metadata (required)
-* └── content          # Resource content (required)
-* ```
-*
-* resource.json format:
-* ```json
-* {
-*   "name": "resource-name",      // required
-*   "type": "text",               // required
-*   "version": "1.0.0",           // required
-*   "domain": "localhost",        // optional, defaults to "localhost"
-*   "path": "optional/path"       // optional
-* }
-* ```
-*/
-declare class FolderLoader implements ResourceLoader {
-	canLoad(source: string): Promise<boolean>;
-	load(folderPath: string): Promise<RXR>;
-}
-/**
-* Configuration options for loadResource.
-*/
-interface LoadResourceConfig {
-	/**
-	* Custom loader to use. If not provided, defaults to FolderLoader.
-	*/
-	loader?: ResourceLoader;
-}
-/**
-* Load a resource from a given source using a ResourceLoader.
-*
-* By default, uses FolderLoader which expects:
-* ```
-* folder/
-* ├── resource.json    # Resource metadata
-* └── content          # Resource content
-* ```
-*
-* You can provide a custom loader via config.loader to support other formats
-* (e.g., zip, tar.gz, URLs).
-*
-* @param source - Source path or identifier
-* @param config - Optional configuration
-* @returns Complete RXR object ready for registry.link()
-* @throws ResourceXError if the source cannot be loaded
-*
-* @example
-* ```typescript
-* // Load from folder (default)
-* const rxr = await loadResource("./my-resource");
-* await registry.link(rxr);
-*
-* // Load with custom loader
-* const rxr = await loadResource("resource.zip", {
-*   loader: new ZipLoader()
-* });
-* ```
-*/
-declare function loadResource(source: string, config?: LoadResourceConfig): Promise<RXR>;
-export { textType, parseRXL, loadResource, loadRXC, jsonType, getResourceType, defineResourceType, createTypeHandlerChain, createRXM, createRXC, clearResourceTypes, builtinTypes, binaryType, TypeHandlerChain, ResourceXError, ResourceTypeError, ResourceType, ResourceSerializer, ResourceResolver, ResourceLoader, RXR, RXM, RXL, RXC, ManifestError, ManifestData, LocatorError, LoadResourceConfig, FolderLoader, ContentError };
+export { parseRXL, createRXM, createRXC, ResourceXError, RXR, RXM, RXL, RXCInput, RXC, ManifestError, ManifestData, LocatorError, ContentError };