@resourcexjs/core 0.4.0 → 0.7.0

package/dist/index.d.ts

@@ -1,349 +1,213 @@
 /**
-* ResourceX Error Types
-*/
-/**
-* Base error class for all ResourceX errors
+* ResourceX Error hierarchy
 */
 declare class ResourceXError extends Error {
 	constructor(message: string, options?: ErrorOptions);
 }
-/**
-* Error thrown when ARP URL parsing fails
-*/
-declare class ParseError extends ResourceXError {
-	readonly url?: string;
-	constructor(message: string, url?: string);
+declare class LocatorError extends ResourceXError {
+	readonly locator?: string;
+	constructor(message: string, locator?: string);
 }
-/**
-* Error thrown when transport layer fails
-*/
-declare class TransportError extends ResourceXError {
-	readonly transport?: string;
-	constructor(message: string, transport?: string, options?: ErrorOptions);
+declare class ManifestError extends ResourceXError {
+	constructor(message: string);
 }
-/**
-* Error thrown when semantic layer fails
-*/
-declare class SemanticError extends ResourceXError {
-	readonly semantic?: string;
-	constructor(message: string, semantic?: string, options?: ErrorOptions);
+declare class ContentError extends ResourceXError {
+	constructor(message: string);
 }
-interface ParsedARP {
-	semantic: string;
-	transport: string;
-	location: string;
+declare class ResourceTypeError extends ResourceXError {
+	constructor(message: string);
 }
 /**
-* Parse an ARP URL into its components
+* RXL - ResourceX Locator
 *
-* @example
-* parseARP("arp:text:https://example.com/file.txt")
-* // { semantic: "text", transport: "https", location: "example.com/file.txt" }
-*/
-declare function parseARP(url: string): ParsedARP;
-/**
-* Transport Handler Interface
-* Responsible for I/O primitives - read, write, list, exists, delete
-* Transport only handles WHERE and HOW to access bytes, not WHAT they mean
-*/
-/**
-* Transport capabilities declaration
+* Format: [domain/path/]name[.type][@version]
 */
-interface TransportCapabilities {
-	readonly canRead: boolean;
-	readonly canWrite: boolean;
-	readonly canList: boolean;
-	readonly canDelete: boolean;
-	readonly canStat: boolean;
+interface RXL {
+	readonly domain?: string;
+	readonly path?: string;
+	readonly name: string;
+	readonly type?: string;
+	readonly version?: string;
+	toString(): string;
 }
 /**
-* Resource stat information
+* Parse a resource locator string into RXL object.
+*
+* Format: [domain/path/]name[.type][@version]
 */
-interface ResourceStat {
-	size: number;
-	modifiedAt?: Date;
-	isDirectory?: boolean;
-}
+declare function parseRXL(locator: string): RXL;
 /**
-* Transport Handler - provides I/O primitives
+* RXM - ResourceX Manifest
 */
-interface TransportHandler {
-	/**
-	* Transport name (e.g., "https", "file", "s3")
-	*/
-	readonly name: string;
-	/**
-	* Transport capabilities
-	*/
-	readonly capabilities: TransportCapabilities;
-	/**
-	* Read content from location
-	* @param location - The location string after ://
-	* @returns Raw content as Buffer
-	*/
-	read(location: string): Promise<Buffer>;
-	/**
-	* Write content to location
-	* @param location - The location string after ://
-	* @param content - Content to write
-	*/
-	write?(location: string, content: Buffer): Promise<void>;
-	/**
-	* List entries at location (for directory-like transports)
-	* @param location - The location string after ://
-	* @returns Array of entry names
-	*/
-	list?(location: string): Promise<string[]>;
-	/**
-	* Create directory at location
-	* @param location - The location string after ://
-	*/
-	mkdir?(location: string): Promise<void>;
-	/**
-	* Check if resource exists at location
-	* @param location - The location string after ://
-	*/
-	exists?(location: string): Promise<boolean>;
-	/**
-	* Get resource stat information
-	* @param location - The location string after ://
-	*/
-	stat?(location: string): Promise<ResourceStat>;
-	/**
-	* Delete resource at location
-	* @param location - The location string after ://
-	*/
-	delete?(location: string): Promise<void>;
-}
-declare class HttpTransportHandler implements TransportHandler {
+interface RXM {
+	readonly domain: string;
+	readonly path?: string;
 	readonly name: string;
-	private readonly protocol;
-	readonly capabilities: TransportCapabilities;
-	constructor(protocol?: "http" | "https");
-	read(location: string): Promise<Buffer>;
-}
-declare const httpsHandler: HttpTransportHandler;
-declare const httpHandler: HttpTransportHandler;
-declare class FileTransportHandler implements TransportHandler {
-	readonly name = "file";
-	readonly capabilities: TransportCapabilities;
-	private resolvePath;
-	read(location: string): Promise<Buffer>;
-	write(location: string, content: Buffer): Promise<void>;
-	list(location: string): Promise<string[]>;
-	mkdir(location: string): Promise<void>;
-	exists(location: string): Promise<boolean>;
-	stat(location: string): Promise<ResourceStat>;
-	delete(location: string): Promise<void>;
+	readonly type: string;
+	readonly version: string;
+	toLocator(): string;
+	toJSON(): ManifestData;
 }
-declare const fileHandler: FileTransportHandler;
-interface DeepracticeConfig {
-	/**
-	* Parent directory for .deepractice folder
-	* @default homedir()
-	*/
-	parentDir?: string;
+interface ManifestData {
+	domain?: string;
+	path?: string;
+	name?: string;
+	type?: string;
+	version?: string;
 }
 /**
-* Create deepractice transport handler
-* Maps deepractice://path to parentDir/.deepractice/path
-*
-* @example
-* ```typescript
-* const handler = deepracticeHandler();
-* // → ~/.deepractice/
+* Create a manifest from data object.
+*/
+declare function createRXM(data: ManifestData): RXM;
+/**
+* RXC - ResourceX Content
 *
-* const handler = deepracticeHandler({ parentDir: "/var/data" });
-* // → /var/data/.deepractice/
-* ```
+* Represents resource content as a stream.
 */
-declare function deepracticeHandler(config?: DeepracticeConfig): TransportHandler;
+interface RXC {
+	/** Content as a readable stream */
+	readonly stream: ReadableStream<Uint8Array>;
+	/** Read content as text */
+	text(): Promise<string>;
+	/** Read content as Buffer */
+	buffer(): Promise<Buffer>;
+	/** Read content as JSON */
+	json<T>(): Promise<T>;
+}
 /**
-* Get transport handler by name
+* Create RXC from string, Buffer, or ReadableStream.
 */
-declare function getTransportHandler(name: string): TransportHandler;
+declare function createRXC(data: string | Buffer | ReadableStream<Uint8Array>): RXC;
 /**
-* Register a custom transport handler
+* Load RXC from file path or URL.
 */
-declare function registerTransportHandler(handler: TransportHandler): void;
+declare function loadRXC(source: string): Promise<RXC>;
 /**
-* Resource metadata
+* RXR (ResourceX Resource) - Complete resource object.
+* A pure data transfer object combining locator, manifest, and content.
 */
-interface ResourceMeta {
-	url: string;
-	semantic: string;
-	transport: string;
-	location: string;
-	size: number;
-	encoding?: string;
-	mimeType?: string;
-	resolvedAt: string;
+interface RXR {
+	locator: RXL;
+	manifest: RXM;
+	content: RXC;
 }
 /**
-* Context passed to semantic handler
+* ResourceSerializer - Handles RXR serialization/deserialization for storage.
 */
-interface SemanticContext {
-	url: string;
-	semantic: string;
-	transport: string;
-	location: string;
-	timestamp: Date;
+interface ResourceSerializer {
+	/**
+	* Serialize RXR to storage format.
+	*/
+	serialize(rxr: RXR): Promise<Buffer>;
+	/**
+	* Deserialize storage data to RXR.
+	*/
+	deserialize(data: Buffer, manifest: RXM): Promise<RXR>;
 }
 /**
-* Base resource interface
+* ResourceResolver - Transforms RXR into usable object.
 */
-interface Resource<T = unknown> {
-	type: string;
-	content: T;
-	meta: ResourceMeta;
+interface ResourceResolver<T = unknown> {
+	/**
+	* Resolve RXR content into a usable object.
+	*/
+	resolve(rxr: RXR): Promise<T>;
 }
 /**
-* Semantic handler interface
-* Semantic orchestrates Transport primitives to resolve/deposit resources
+* ResourceType - Defines how a resource type is handled.
 */
-interface SemanticHandler<T = unknown> {
+interface ResourceType<T = unknown> {
 	/**
-	* Semantic name (e.g., "text", "json", "package")
+	* Type name (e.g., "text", "json", "binary").
 	*/
-	readonly name: string;
+	name: string;
 	/**
-	* Resolve resource from location
-	* Semantic controls how to use transport primitives to fetch and parse resource
-	*
-	* @param transport - Transport handler for I/O operations
-	* @param location - Resource location
-	* @param context - Semantic context
+	* Alternative names for this type (e.g., ["txt", "plaintext"]).
 	*/
-	resolve(transport: TransportHandler, location: string, context: SemanticContext): Promise<Resource<T>>;
+	aliases?: string[];
 	/**
-	* Deposit resource to location
-	* Semantic controls how to serialize data and use transport primitives to store
-	*
-	* @param transport - Transport handler for I/O operations
-	* @param location - Resource location
-	* @param data - Data to deposit
-	* @param context - Semantic context
+	* Human-readable description.
 	*/
-	deposit?(transport: TransportHandler, location: string, data: T, context: SemanticContext): Promise<void>;
+	description: string;
 	/**
-	* Check if resource exists at location
-	*
-	* @param transport - Transport handler for I/O operations
-	* @param location - Resource location
-	* @param context - Semantic context
+	* Serializer for storage operations.
 	*/
-	exists?(transport: TransportHandler, location: string, context: SemanticContext): Promise<boolean>;
+	serializer: ResourceSerializer;
 	/**
-	* Delete resource at location
-	*
-	* @param transport - Transport handler for I/O operations
-	* @param location - Resource location
-	* @param context - Semantic context
+	* Resolver to transform RXR into usable object.
 	*/
-	delete?(transport: TransportHandler, location: string, context: SemanticContext): Promise<void>;
-}
-interface TextResource extends Resource<string> {
-	type: "text";
-	content: string;
-}
-declare class TextSemanticHandler implements SemanticHandler<string> {
-	readonly name = "text";
-	resolve(transport: TransportHandler, location: string, context: SemanticContext): Promise<TextResource>;
-	deposit(transport: TransportHandler, location: string, data: string, _context: SemanticContext): Promise<void>;
-	exists(transport: TransportHandler, location: string, _context: SemanticContext): Promise<boolean>;
-	delete(transport: TransportHandler, location: string, _context: SemanticContext): Promise<void>;
-}
-declare const textHandler: TextSemanticHandler;
-interface BinaryResource extends Resource<Buffer> {
-	type: "binary";
-	content: Buffer;
-}
-/**
-* Supported binary input types for deposit
-*/
-type BinaryInput = Buffer | Uint8Array | ArrayBuffer | number[];
-declare class BinarySemanticHandler implements SemanticHandler<Buffer> {
-	readonly name = "binary";
-	resolve(transport: TransportHandler, location: string, context: SemanticContext): Promise<BinaryResource>;
-	deposit(transport: TransportHandler, location: string, data: BinaryInput, _context: SemanticContext): Promise<void>;
-	exists(transport: TransportHandler, location: string, _context: SemanticContext): Promise<boolean>;
-	delete(transport: TransportHandler, location: string, _context: SemanticContext): Promise<void>;
+	resolver: ResourceResolver<T>;
 }
-declare const binaryHandler: BinarySemanticHandler;
-/**
-* Get semantic handler by name
-*/
-declare function getSemanticHandler(name: string): SemanticHandler;
 /**
-* Register a custom semantic handler
+* Define and register a resource type.
+*
+* @throws ResourceTypeError if type is already registered
 */
-declare function registerSemanticHandler(handler: SemanticHandler): void;
+declare function defineResourceType<T>(config: ResourceType<T>): ResourceType<T>;
 /**
-* Resolve an ARP URL to a resource
+* Get a registered resource type by name.
 *
-* @example
-* const resource = await resolve("arp:text:https://example.com/file.txt");
-* // { type: "text", content: "...", meta: { ... } }
+* @returns ResourceType or undefined if not found
 */
-declare function resolve(url: string): Promise<Resource>;
+declare function getResourceType<T = unknown>(name: string): ResourceType<T> | undefined;
 /**
-* Deposit data to an ARP URL
-*
-* @example
-* await deposit("arp:text:file://./data/config.txt", "hello world");
+* Clear all registered resource types (for testing).
 */
-declare function deposit(url: string, data: unknown): Promise<void>;
+declare function clearResourceTypes(): void;
 /**
-* Check if resource exists at ARP URL
-*
-* @example
-* const exists = await resourceExists("arp:text:file://./data/config.txt");
+* Text resource type
 */
-declare function resourceExists(url: string): Promise<boolean>;
+declare const textType: ResourceType<string>;
 /**
-* Delete resource at ARP URL
-*
-* @example
-* await resourceDelete("arp:text:file://./data/config.txt");
+* JSON resource type
 */
-declare function resourceDelete(url: string): Promise<void>;
+declare const jsonType: ResourceType<unknown>;
 /**
-* Resource Definition Types
+* Binary resource type
 */
+declare const binaryType: ResourceType<Buffer>;
 /**
-* Definition of a custom resource (shortcut for ARP URL)
+* All built-in types
 */
-interface ResourceDefinition {
-	/** Unique name for the resource (used in URL: name://location) */
-	readonly name: string;
-	/** Semantic type (e.g., "text", "json", "binary") */
-	readonly semantic: string;
-	/** Transport type (e.g., "file", "https") */
-	readonly transport: string;
-	/** Base path prepended to location (optional) */
-	readonly basePath?: string;
-}
+declare const builtinTypes: ResourceType[];
 /**
-* Create a new resource registry (isolated instance)
+* TypeHandlerChain - Responsibility chain for resource type handling.
+* Manages type registration and delegates serialization/deserialization.
 */
-declare function createResourceRegistry(): {
+declare class TypeHandlerChain {
+	private handlers;
 	/**
-	* Register a resource definition
+	* Register a resource type handler.
+	* Registers both the type name and its aliases.
 	*/
-	register(definition: ResourceDefinition): void
+	register(type: ResourceType): void;
 	/**
-	* Get a resource definition by name
+	* Register multiple type handlers.
 	*/
-	get(name: string): ResourceDefinition | undefined
+	registerAll(types: ResourceType[]): void;
 	/**
-	* Check if a resource is registered
+	* Check if a type is supported.
 	*/
-	has(name: string): boolean
+	canHandle(typeName: string): boolean;
 	/**
-	* Clear all registered resources
+	* Get handler for a type.
 	*/
-	clear(): void
-};
-type ResourceRegistry = ReturnType<typeof createResourceRegistry>;
-declare const VERSION: string;
-export { textHandler, resourceExists, resourceDelete, resolve, registerTransportHandler, registerSemanticHandler, parseARP, httpsHandler, httpHandler, getTransportHandler, getSemanticHandler, fileHandler, deposit, deepracticeHandler, createResourceRegistry, binaryHandler, VERSION, TransportHandler, TransportError, TransportCapabilities, TextResource, SemanticHandler, SemanticError, SemanticContext, ResourceXError, ResourceStat, ResourceRegistry, ResourceMeta, ResourceDefinition, Resource, ParsedARP, ParseError, DeepracticeConfig, BinaryResource, BinaryInput };
+	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;
+export { textType, parseRXL, loadRXC, jsonType, getResourceType, defineResourceType, createTypeHandlerChain, createRXM, createRXC, clearResourceTypes, builtinTypes, binaryType, TypeHandlerChain, ResourceXError, ResourceTypeError, ResourceType, ResourceSerializer, ResourceResolver, RXR, RXM, RXL, RXC, ManifestError, ManifestData, LocatorError, ContentError };