@resourcexjs/core 2.4.1 → 2.5.1

package/dist/index.d.ts

@@ -14,130 +14,167 @@ declare class ManifestError extends ResourceXError {
 declare class ContentError extends ResourceXError {
 	constructor(message: string);
 }
+declare class DefinitionError extends ResourceXError {
+	constructor(message: string);
+}
 /**
-* RXL - ResourceX Locator
+* RXD - ResourceX Definition
 *
-* Format: [domain/path/]name[.type][@version]
+* The content of resource.json file.
+* Contains all metadata for a resource in development.
 */
-interface RXL {
-	readonly domain?: string;
-	readonly path?: string;
+interface RXD {
 	readonly name: string;
-	readonly type?: string;
-	readonly version?: string;
-	toString(): string;
+	readonly type: string;
+	readonly tag?: string;
+	readonly registry?: string;
+	readonly path?: string;
+	readonly description?: string;
+	readonly author?: string;
+	readonly license?: string;
+	readonly keywords?: string[];
+	readonly repository?: string;
+	readonly [key: string]: unknown;
 }
 /**
-* Parse a resource locator string into RXL object.
+* RXL - ResourceX Locator
+*
+* Unique identifier for a resource (pure data object).
+* Docker-style format with optional tag.
+*
+* Format: [registry/][path/]name[:tag]
 *
-* Format: [domain/path/]name[.type][@version]
+* Examples:
+* - hello                    → name=hello, tag=latest (default)
+* - hello:1.0.0             → name=hello, tag=1.0.0
+* - prompts/hello:stable    → path=prompts, name=hello, tag=stable
+* - localhost:3098/hello:1.0.0 → registry=localhost:3098, name=hello, tag=1.0.0
+* - registry.example.com/org/hello:latest → registry=registry.example.com, path=org, name=hello, tag=latest
 */
-declare function parseRXL(locator: string): RXL;
+interface RXL {
+	/** Registry host:port (e.g., "localhost:3098", "registry.example.com") */
+	readonly registry?: string;
+	/** Path within registry (e.g., "org", "prompts") */
+	readonly path?: string;
+	/** Resource name */
+	readonly name: string;
+	/** Tag (version or label). Defaults to "latest" if not specified. */
+	readonly tag: string;
+}
 /**
 * RXM - ResourceX Manifest
+*
+* Resource metadata stored within the resource (pure data object).
 */
 interface RXM {
-	readonly domain: string;
+	readonly registry?: string;
 	readonly path?: string;
 	readonly name: string;
 	readonly type: string;
-	readonly version: string;
-	toLocator(): string;
-	toJSON(): ManifestData;
-}
-interface ManifestData {
-	domain?: string;
-	path?: string;
-	name?: string;
-	type?: string;
-	version?: string;
-}
-/**
-* Create a manifest from data object.
-*/
-declare function createRXM(data: ManifestData): RXM;
-/**
-* PathNode - Tree structure node for package file hierarchy.
-*/
-interface PathNode {
-	/** File or directory name */
-	name: string;
-	/** Node type */
-	type: "file" | "directory";
-	/** Children nodes (only for directories) */
-	children?: PathNode[];
+	readonly tag: string;
+	readonly files?: string[];
 }
 /**
 * RXA - ResourceX Archive
 *
 * Archive container (tar.gz format) for storage and transfer.
-* Use extract() to get RXP for file access.
 */
 interface RXA {
 	/** Content as a readable stream (tar.gz format) */
 	readonly stream: ReadableStream<Uint8Array>;
 	/** Get raw archive buffer (tar.gz format) */
 	buffer(): Promise<Buffer>;
-	/** Extract archive to package for file access */
-	extract(): Promise<RXP>;
 }
 /**
-* RXP - ResourceX Package
+* RXR - ResourceX Resource
 *
-* Extracted package for runtime file access.
-* Created from RXA.extract(), can pack back with pack().
+* Complete resource object combining locator, manifest, and archive.
 */
-interface RXP {
-	/** Get flat list of all file paths */
-	paths(): string[];
-	/** Get tree structure of files and directories */
-	tree(): PathNode[];
-	/** Read a specific file from the package */
-	file(path: string): Promise<Buffer>;
-	/** Read all files from the package */
-	files(): Promise<Map<string, Buffer>>;
-	/** Pack back to archive */
-	pack(): Promise<RXA>;
+interface RXR {
+	readonly locator: RXL;
+	readonly manifest: RXM;
+	readonly archive: RXA;
 }
 /**
-* Input type for createRXA.
-* - Files record: { 'path/to/file': content }
-* - Buffer: { buffer: tarGzBuffer }
+* Parse and validate a resource definition (resource.json content).
+*
+* @param input - The raw JSON object to parse
+* @returns A validated RXD object
+* @throws DefinitionError if validation fails
 */
-type RXAInput = Record<string, Buffer | Uint8Array | string> | {
-	buffer: Buffer
-};
+declare function define(input: unknown): RXD;
 /**
-* Create RXA from files or existing buffer.
-*
-* @example
-* ```typescript
-* // Single file
-* const archive = await createRXA({ 'content': Buffer.from('Hello') });
-*
-* // Multiple files
-* const archive = await createRXA({
-*   'index.ts': Buffer.from('1'),
-*   'styles.css': Buffer.from('body {}'),
-* });
-*
-* // From existing tar.gz buffer
-* const archive = await createRXA({ buffer: existingTarGzBuffer });
-*
-* // Extract to package
-* const pkg = await archive.extract();
-* const paths = pkg.paths();
-* const content = await pkg.file('index.ts');
-* ```
+* Create RXM from RXD.
+* Extracts only the core metadata fields (pure data object).
+*
+* @param rxd - Resource definition
+* @returns RXM manifest object
 */
-declare function createRXA(input: RXAInput): Promise<RXA>;
+declare function manifest(rxd: RXD): RXM;
 /**
-* RXR (ResourceX Resource) - Complete resource object.
-* A pure data transfer object combining locator, manifest, and archive.
+* Create RXA from files.
+*
+* @param files - Record of file paths to Buffer contents
+* @returns RXA archive object
 */
-interface RXR {
-	locator: RXL;
-	manifest: RXM;
-	archive: RXA;
-}
-export { parseRXL, createRXM, createRXA, ResourceXError, RXR, RXP, RXM, RXL, RXAInput, RXA, PathNode, ManifestError, ManifestData, LocatorError, ContentError };
+declare function archive(files: Record<string, Buffer>): Promise<RXA>;
+/**
+* Create RXL from RXM.
+*
+* @param rxm - Resource manifest
+* @returns RXL locator object (pure data)
+*/
+declare function locate(rxm: RXM): RXL;
+/**
+* Create RXR from RXM and RXA.
+*
+* @param rxm - Resource manifest
+* @param rxa - Resource archive
+* @returns RXR resource object
+*/
+declare function resource(rxm: RXM, rxa: RXA): RXR;
+/**
+* Extract files from RXA.
+*
+* @param rxa - Resource archive
+* @returns Record of file paths to Buffer contents
+*/
+declare function extract(rxa: RXA): Promise<Record<string, Buffer>>;
+/**
+* Format RXL to locator string.
+*
+* Docker-style format: [registry/][path/]name[:tag]
+*
+* Examples:
+* - { name: "hello", tag: "latest" } → "hello" (omit :latest)
+* - { name: "hello", tag: "1.0.0" } → "hello:1.0.0"
+* - { registry: "localhost:3098", name: "hello", tag: "1.0.0" } → "localhost:3098/hello:1.0.0"
+*
+* @param rxl - Resource locator
+* @returns Locator string
+*/
+declare function format(rxl: RXL): string;
+/**
+* Parse locator string to RXL.
+*
+* Docker-style format: [registry/][path/]name[:tag]
+*
+* Examples:
+* - hello                    → name=hello, tag=latest
+* - hello:1.0.0             → name=hello, tag=1.0.0
+* - prompts/hello:stable    → path=prompts, name=hello, tag=stable
+* - localhost:3098/hello:1.0.0 → registry=localhost:3098, name=hello, tag=1.0.0
+*
+* @param locator - Locator string
+* @returns RXL object
+* @throws LocatorError if parsing fails
+*/
+declare function parse(locator: string): RXL;
+/**
+* Wrap existing tar.gz buffer as RXA.
+*
+* @param buffer - Existing tar.gz buffer
+* @returns RXA archive object
+*/
+declare function wrap(buffer: Buffer): RXA;
+export { wrap, resource, parse, manifest, locate, format, extract, define, archive, ResourceXError, RXR, RXM, RXL, RXD, RXA, ManifestError, LocatorError, DefinitionError, ContentError };