@resourcexjs/registry 2.4.0 → 2.5.0

package/dist/index.d.ts

@@ -1,6 +1,4 @@
-import { RXR as RXR3, RXL as RXL3 } from "@resourcexjs/core";
-import { BundledType, ResolvedResource, IsolatorType } from "@resourcexjs/type";
-import { RXR, RXL } from "@resourcexjs/core";
+import { RXL, RXR } from "@resourcexjs/core";
 /**
 * Search options for querying resources.
 */
@@ -19,304 +17,155 @@ interface SearchOptions {
 	offset?: number;
 }
 /**
-* Storage interface - pure storage abstraction.
-* Handles CRUD operations for resources.
+* Registry interface - business layer for RXR operations.
 *
-* Different implementations:
-* - LocalStorage: filesystem, read-write
-* - GitStorage: git clone, read-only
-* - HttpStorage: HTTP API, typically read-only
+* This interface defines CRUD operations on RXR objects.
+* Different implementations (HostedRegistry, MirrorRegistry, LinkedRegistry)
+* provide different semantics on top of the same Storage layer.
 */
-interface Storage {
-	/**
-	* Storage type identifier.
-	*/
-	readonly type: string;
+interface Registry {
 	/**
 	* Get resource by locator.
 	* @throws RegistryError if not found
 	*/
-	get(locator: string): Promise<RXR>;
+	get(rxl: RXL): Promise<RXR>;
 	/**
-	* Store a resource.
-	* @throws RegistryError if storage is read-only
+	* Store resource.
 	*/
 	put(rxr: RXR): Promise<void>;
 	/**
 	* Check if resource exists.
 	*/
-	exists(locator: string): Promise<boolean>;
+	has(rxl: RXL): Promise<boolean>;
 	/**
-	* Delete a resource.
-	* @throws RegistryError if storage is read-only
+	* Delete resource.
 	*/
-	delete(locator: string): Promise<void>;
-	/**
-	* Search for resources.
-	*/
-	search(options?: SearchOptions): Promise<RXL[]>;
-}
-import { RXR as RXR2, RXL as RXL2 } from "@resourcexjs/core";
-/**
-* LocalStorage configuration.
-*/
-interface LocalStorageConfig {
+	remove(rxl: RXL): Promise<void>;
 	/**
-	* Base path for storage. Defaults to ~/.resourcex
+	* List resources matching options.
 	*/
-	path?: string;
+	list(options?: SearchOptions): Promise<RXL[]>;
 }
+import { RXL as RXL2, RXR as RXR2 } from "@resourcexjs/core";
+import { Storage } from "@resourcexjs/storage";
 /**
-* Local filesystem storage implementation.
-* Uses ARP file transport for I/O operations.
+* HostedRegistry - Registry for resources you own (authoritative data).
 *
+* Uses Storage layer for persistence.
 * Storage structure:
-* - {basePath}/{domain}/{path}/{name}.{type}/{version}/
-*   - manifest.json
-*   - archive.tar.gz
-*
-* For localhost/no-domain resources:
-* - {basePath}/localhost/{name}.{type}/{version}/
+*   {domain}/{path}/{name}.{type}/{version}/
+*     - manifest.json
+*     - archive.tar.gz
 */
-declare class LocalStorage implements Storage {
-	readonly type = "local";
-	private readonly basePath;
-	private readonly arp;
-	constructor(config?: LocalStorageConfig);
-	/**
-	* Create ARP URL for a file path.
-	*/
-	private toArpUrl;
-	/**
-	* Build filesystem path for a resource.
-	* Path: {basePath}/{domain}/{path}/{name}.{type}/{version}
-	*/
-	private buildPath;
-	/**
-	* Check if a resource exists at a specific path.
-	* Handles both regular storage (manifest.json) and symlinked dev directories (resource.json).
-	*/
-	private existsAt;
-	/**
-	* Check if a path is a symlink.
-	*/
-	private isSymlink;
+declare class HostedRegistry implements Registry {
+	private readonly storage;
+	constructor(storage: Storage);
 	/**
-	* Load resource from a specific path.
-	* If path is a symlink, loads from the linked directory.
+	* Build storage key prefix for a resource.
 	*/
-	private loadFrom;
-	get(locator: string): Promise<RXR2>;
+	private buildKeyPrefix;
+	get(rxl: RXL2): Promise<RXR2>;
 	put(rxr: RXR2): Promise<void>;
-	exists(locator: string): Promise<boolean>;
-	delete(locator: string): Promise<void>;
-	search(options?: SearchOptions): Promise<RXL2[]>;
-	/**
-	* Link a development directory.
-	* Creates a symlink so changes are reflected immediately.
-	*/
-	link(path: string): Promise<void>;
-	/**
-	* Parse entry path to RXL.
-	* Entry format: {domain}/{path}/{name}.{type}/{version}/manifest.json
-	*/
-	private parseEntryToRXL;
-}
-/**
-* Registry configuration.
-*/
-interface RegistryConfig {
-	/**
-	* Storage backend. Defaults to LocalStorage.
-	*/
-	storage?: Storage;
-	/**
-	* Mirror URL for remote fetch (client mode).
-	* If configured, tries mirror before well-known discovery.
-	*/
-	mirror?: string;
-	/**
-	* Additional custom resource types to support.
-	* Built-in types (text, json, binary) are always included by default.
-	*/
-	types?: BundledType[];
-	/**
-	* Isolator type for resolver execution (SandboX).
-	* - "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)
-	*/
-	isolator?: IsolatorType;
-}
-/**
-* Registry interface for resource management.
-*/
-interface Registry {
-	/**
-	* Add support for a custom resource type.
-	*/
-	supportType(type: BundledType): void;
-	/**
-	* Link a development directory.
-	* Creates a symlink so changes are reflected immediately.
-	* Only supported by LocalStorage.
-	*/
-	link(path: string): Promise<void>;
-	/**
-	* Add resource to storage.
-	* @param source - Resource directory path or RXR object
-	*/
-	add(source: string | RXR3): Promise<void>;
-	/**
-	* Get raw resource by locator.
-	*
-	* Flow:
-	* - localhost: Only queries local storage
-	* - Other domains: Local cache -> [Mirror] -> Source (well-known)
-	*/
-	get(locator: string): Promise<RXR3>;
-	/**
-	* Resolve resource by locator.
-	* Returns ResolvedResource with execute function.
-	*/
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource<TArgs, TResult>>;
+	has(rxl: RXL2): Promise<boolean>;
+	remove(rxl: RXL2): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL2[]>;
 	/**
-	* Check if resource exists.
+	* Parse storage key to RXL.
+	* Key format: {domain}/{path}/{name}.{type}/{version}/manifest.json
 	*/
-	exists(locator: string): Promise<boolean>;
-	/**
-	* Delete resource from storage.
-	*/
-	delete(locator: string): Promise<void>;
-	/**
-	* Search for resources.
-	*/
-	search(options?: SearchOptions): Promise<RXL3[]>;
+	private parseKeyToRXL;
 }
+import { RXL as RXL3, RXR as RXR3 } from "@resourcexjs/core";
+import { Storage as Storage2 } from "@resourcexjs/storage";
 /**
-* Default Registry implementation.
+* MirrorRegistry - Registry for cached/mirrored remote resources.
 *
-* Combines Storage (for CRUD) with TypeHandlerChain (for type resolution).
-* Supports remote fetch for non-localhost domains.
+* Similar to HostedRegistry but adds cache management methods.
+* Resources can be cleared (evicted from cache).
+*
+* Storage structure:
+*   {domain}/{path}/{name}.{type}/{version}/
+*     - manifest.json
+*     - archive.tar.gz
 */
-declare class DefaultRegistry implements Registry {
+declare class MirrorRegistry implements Registry {
 	private readonly storage;
-	private readonly mirror?;
-	private readonly typeHandler;
-	private readonly executor;
-	private readonly discoveryCache;
-	constructor(config?: RegistryConfig);
-	supportType(type: BundledType): void;
-	link(path: string): Promise<void>;
-	add(source: string | RXR3): Promise<void>;
-	get(locator: string): Promise<RXR3>;
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource<TArgs, TResult>>;
-	exists(locator: string): Promise<boolean>;
-	delete(locator: string): Promise<void>;
-	search(options?: SearchOptions): Promise<RXL3[]>;
+	constructor(storage: Storage2);
 	/**
-	* Fetch resource from remote.
-	* Flow: Mirror (if configured) -> Source (well-known)
+	* Build storage key prefix for a resource.
 	*/
-	private fetchRemote;
+	private buildKeyPrefix;
+	get(rxl: RXL3): Promise<RXR3>;
+	put(rxr: RXR3): Promise<void>;
+	has(rxl: RXL3): Promise<boolean>;
+	remove(rxl: RXL3): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL3[]>;
 	/**
-	* Discover registry endpoint for a domain via well-known.
+	* Clear cached resources.
+	* @param domain - If provided, only clear resources from this domain
 	*/
-	private discoverEndpoint;
+	clear(domain?: string): Promise<void>;
 	/**
-	* Fetch resource from a specific endpoint via HTTP API.
+	* Parse storage key to RXL.
+	* Key format: {domain}/{path}/{name}.{type}/{version}/manifest.json
 	*/
-	private fetchFromEndpoint;
+	private parseKeyToRXL;
 }
-import { BundledType as BundledType2, IsolatorType as IsolatorType2 } from "@resourcexjs/type";
+import { RXL as RXL4, RXR as RXR4 } from "@resourcexjs/core";
 /**
-* Client registry configuration.
-* Uses LocalStorage as cache, optionally fetches from remote via mirror or well-known.
+* LinkedRegistry - Registry for development symlinks.
+*
+* Creates symlinks to development directories so changes are reflected immediately.
+* Unlike HostedRegistry/MirrorRegistry, it doesn't use Storage layer directly.
+* Instead, it manages symlinks in a base directory.
+*
+* Storage structure:
+*   {basePath}/{domain}/{path}/{name}.{type}/{version} → /path/to/dev/folder
 */
-interface ClientRegistryConfig {
+declare class LinkedRegistry implements Registry {
+	private readonly basePath;
+	constructor(basePath: string);
 	/**
-	* Local cache path. Defaults to ~/.resourcex
+	* Build symlink path for a resource.
 	*/
-	path?: string;
+	private buildLinkPath;
 	/**
-	* Mirror URL for remote fetch.
-	* If configured, tries mirror before well-known discovery.
+	* Check if a path is a symlink.
 	*/
-	mirror?: string;
+	private isSymlink;
+	get(rxl: RXL4): Promise<RXR4>;
 	/**
-	* Additional custom resource types.
-	* Built-in types (text, json, binary) are always included.
+	* Put is not typically used for LinkedRegistry.
+	* Use link() instead to create symlinks.
 	*/
-	types?: BundledType2[];
+	put(_rxr: RXR4): Promise<void>;
+	has(rxl: RXL4): Promise<boolean>;
+	remove(rxl: RXL4): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL4[]>;
 	/**
-	* Isolator type for resolver execution.
-	* Defaults to "none".
+	* Link a development directory.
+	* Creates a symlink so changes are reflected immediately.
+	*
+	* @param devPath - Path to development directory (must contain resource.json)
+	* @returns The RXL of the linked resource
 	*/
-	isolator?: IsolatorType2;
-}
-/**
-* Server registry configuration.
-* Uses custom Storage implementation.
-*/
-interface ServerRegistryConfig {
+	link(devPath: string): Promise<RXL4>;
 	/**
-	* Custom storage implementation.
-	* Example: new LocalStorage({ path: "..." })
+	* Unlink a development directory.
+	* Alias for remove().
 	*/
-	storage: Storage;
+	unlink(rxl: RXL4): Promise<void>;
 	/**
-	* Additional custom resource types.
-	* Built-in types (text, json, binary) are always included.
+	* Recursively scan for symlinks.
 	*/
-	types?: BundledType2[];
+	private scanSymlinks;
 	/**
-	* Isolator type for resolver execution.
-	* Defaults to "none".
+	* Parse relative path to RXL.
+	* Path format: {domain}/{path}/{name}.{type}/{version}
 	*/
-	isolator?: IsolatorType2;
+	private parsePathToRXL;
 }
 /**
-* All supported registry configurations.
-*/
-type CreateRegistryConfig = ClientRegistryConfig | ServerRegistryConfig;
-/**
-* Create a registry instance.
-*
-* Built-in types (text, json, binary) are always included by default.
-*
-* Two modes:
-* 1. Client mode (default): Uses LocalStorage as cache, fetches from remote when cache miss
-* 2. Server mode: Uses custom Storage implementation
-*
-* @example
-* // Simple usage - builtin types included
-* const registry = createRegistry();
-*
-* @example
-* // With custom types
-* const registry = createRegistry({ types: [myPromptType] });
-*
-* @example
-* // With isolator (SandboX)
-* const registry = createRegistry({
-*   isolator: "srt",  // or "none", "cloudflare", "e2b"
-* });
-*
-* @example
-* // Server mode - custom storage
-* const registry = createRegistry({
-*   storage: new LocalStorage({ path: "./data" }),
-* });
-*/
-declare function createRegistry(config?: CreateRegistryConfig): Registry;
-/**
 * Well-known discovery response format.
 */
 interface WellKnownResponse {
@@ -343,8 +192,7 @@ import { ResourceXError } from "@resourcexjs/core";
 declare class RegistryError extends ResourceXError {
 	constructor(message: string, options?: ErrorOptions);
 }
-import { RXR as RXR4, RXL as RXL4 } from "@resourcexjs/core";
-import { BundledType as BundledType3, ResolvedResource as ResolvedResource2 } from "@resourcexjs/type";
+import { RXR as RXR5, RXL as RXL5 } from "@resourcexjs/core";
 /**
 * Base class for Registry middleware.
 * Delegates all operations to the inner registry.
@@ -353,20 +201,13 @@ import { BundledType as BundledType3, ResolvedResource as ResolvedResource2 } fr
 declare abstract class RegistryMiddleware implements Registry {
 	protected readonly inner: Registry;
 	constructor(inner: Registry);
-	supportType(type: BundledType3): void;
-	link(path: string): Promise<void>;
-	add(source: string | RXR4): Promise<void>;
-	get(locator: string): Promise<RXR4>;
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource2<TArgs, TResult>>;
-	exists(locator: string): Promise<boolean>;
-	delete(locator: string): Promise<void>;
-	search(options?: SearchOptions): Promise<RXL4[]>;
+	get(rxl: RXL5): Promise<RXR5>;
+	put(rxr: RXR5): Promise<void>;
+	has(rxl: RXL5): Promise<boolean>;
+	remove(rxl: RXL5): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL5[]>;
 }
-import { RXR as RXR5 } from "@resourcexjs/core";
-import { ResolvedResource as ResolvedResource3 } from "@resourcexjs/type";
+import { RXR as RXR6, RXL as RXL6 } from "@resourcexjs/core";
 /**
 * Domain validation middleware.
 * Ensures all resources from this registry match the trusted domain.
@@ -381,20 +222,13 @@ declare class DomainValidation extends RegistryMiddleware {
 	/**
 	* Get resource and validate domain.
 	*/
-	get(locator: string): Promise<RXR5>;
-	/**
-	* Resolve resource and validate domain.
-	*/
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource3<TArgs, TResult>>;
+	get(rxl: RXL6): Promise<RXR6>;
 }
 /**
 * Factory function to create domain validation middleware.
 *
 * @example
-* const registry = withDomainValidation(gitRegistry, "deepractice.ai");
+* const registry = withDomainValidation(hostedRegistry, "deepractice.ai");
 */
 declare function withDomainValidation(registry: Registry, trustedDomain: string): Registry;
-export { withDomainValidation, discoverRegistry, createRegistry, WellKnownResponse, Storage, ServerRegistryConfig, SearchOptions, RegistryMiddleware, RegistryError, RegistryConfig, Registry, LocalStorageConfig, LocalStorage, DomainValidation, DiscoveryResult, DefaultRegistry, CreateRegistryConfig, ClientRegistryConfig };
+export { withDomainValidation, discoverRegistry, WellKnownResponse, SearchOptions, RegistryMiddleware, RegistryError, Registry, MirrorRegistry, LinkedRegistry, HostedRegistry, DomainValidation, DiscoveryResult };