tessl/npm-theia--core

Core framework for building cloud and desktop IDE applications using modern web technologies with TypeScript and dependency injection.

—

Pending

Overview

Eval results

Files

Resources and Files

Name: tessl/npm-theia--core
Author: tessl

Theia's resource system provides unified abstraction for files, URIs, and virtual resources with versioning, encoding support, and multiple resolvers for flexible file system integration.

Capabilities

Resource Interface

Base abstraction for any resource that can be read or modified.

/**
 * Abstract resource interface
 */
interface Resource {
    /** Resource URI */
    readonly uri: URI;
    
    /** Optional version information */
    readonly version?: ResourceVersion;
    
    /** Optional encoding information */
    readonly encoding?: string;
    
    /**
     * Read resource contents
     * @param options - Read options
     * @returns Promise resolving to resource content
     */
    readContents(options?: ResourceReadOptions): Promise<string>;
    
    /**
     * Save resource contents (if supported)
     * @param content - Content to save
     * @param options - Save options
     * @returns Promise that resolves when save completes
     */
    saveContents?(content: string, options?: ResourceSaveOptions): Promise<void>;
    
    /**
     * Get resource stat information
     * @returns Promise resolving to stat info
     */
    stat?(): Promise<ResourceStat>;
    
    /**
     * Delete the resource (if supported)
     * @returns Promise that resolves when delete completes
     */
    delete?(): Promise<void>;
}

/**
 * Resource version for tracking changes
 */
interface ResourceVersion {
    /** Version identifier */
    readonly id: string;
    
    /** Last modification timestamp */
    readonly mtime?: number;
    
    /** Content hash */
    readonly etag?: string;
}

URI System

Universal Resource Identifier handling with cross-platform path support.

/**
 * URI class for resource identification
 */
class URI {
    /** URI scheme (file, http, theia, etc.) */
    readonly scheme: string;
    
    /** URI authority (hostname, etc.) */
    readonly authority: string;
    
    /** URI path */
    readonly path: string;
    
    /** URI query string */
    readonly query: string;
    
    /** URI fragment */
    readonly fragment: string;
    
    /**
     * Create file URI from file system path
     * @param path - File system path
     * @returns File URI
     */
    static file(path: string): URI;
    
    /**
     * Parse URI from string
     * @param value - URI string
     * @returns Parsed URI
     */
    static parse(value: string): URI;
    
    /**
     * Resolve relative URI against this URI
     * @param relative - Relative URI or path
     * @returns Resolved URI
     */
    resolve(relative: string | URI): URI;
    
    /**
     * Get relative path from this URI to target
     * @param target - Target URI
     * @returns Relative path or undefined
     */
    relative(target: URI): string | undefined;
    
    /**
     * Create new URI with modified properties
     * @param change - Properties to change
     * @returns New URI with changes
     */
    with(change: {
        scheme?: string;
        authority?: string;
        path?: string;
        query?: string;
        fragment?: string;
    }): URI;
    
    /**
     * Convert to string representation
     * @returns URI string
     */
    toString(): string;
    
    /**
     * Convert to file system path (file URIs only)
     * @returns File system path
     */
    fsPath: string;
}

Usage Example:

import { URI } from "@theia/core";

// Create file URI
const fileUri = URI.file('/home/user/document.txt');
console.log(fileUri.toString()); // file:///home/user/document.txt

// Parse URI from string
const httpUri = URI.parse('https://example.com/api/data?format=json');
console.log(httpUri.scheme); // https
console.log(httpUri.authority); // example.com
console.log(httpUri.path); // /api/data
console.log(httpUri.query); // format=json

// Resolve relative paths
const baseUri = URI.file('/home/user/');
const resolvedUri = baseUri.resolve('documents/file.txt');
console.log(resolvedUri.fsPath); // /home/user/documents/file.txt

// Modify URI
const modifiedUri = httpUri.with({ 
    query: 'format=xml&limit=10' 
});
console.log(modifiedUri.toString()); // https://example.com/api/data?format=xml&limit=10

Resource Provider

Service for obtaining resources from URIs with caching and resolution.

/**
 * Provider for creating/obtaining resources
 */
interface ResourceProvider {
    /**
     * Get resource for URI
     * @param uri - Resource URI
     * @returns Promise resolving to resource
     */
    get(uri: URI): Promise<Resource>;
    
    /**
     * Check if provider can handle URI scheme
     * @param uri - URI to check
     * @returns True if provider can handle URI
     */
    canHandle(uri: URI): boolean;
}

/**
 * Service token for ResourceProvider
 */
const ResourceProvider: symbol;

Resource Resolver

Lower-level interface for resolving URIs to resources.

/**
 * Resolver for specific URI schemes
 */
interface ResourceResolver {
    /**
     * Resolve URI to resource
     * @param uri - URI to resolve
     * @returns Promise resolving to resource
     */
    resolve(uri: URI): Promise<Resource>;
    
    /**
     * Check if resolver supports URI
     * @param uri - URI to check
     * @returns True if resolver supports URI
     */
    canResolve(uri: URI): boolean;
}

/**
 * Service token for ResourceResolver
 */
const ResourceResolver: symbol;

In-Memory Resources

In-memory resource implementations for virtual files and temporary content.

/**
 * In-memory resource implementation
 */
class InMemoryResource implements Resource {
    readonly uri: URI;
    readonly version?: ResourceVersion;
    
    constructor(uri: URI, content?: string, version?: ResourceVersion);
    
    readContents(): Promise<string>;
    saveContents(content: string): Promise<void>;
    delete(): Promise<void>;
}

/**
 * In-memory text resource with encoding support
 */
class InMemoryTextResource extends InMemoryResource {
    readonly encoding: string;
    
    constructor(uri: URI, content?: string, encoding?: string);
}

/**
 * Collection of in-memory resources
 */
class InMemoryResources {
    /**
     * Add resource to collection
     * @param resource - Resource to add
     */
    add(resource: InMemoryResource): void;
    
    /**
     * Get resource by URI
     * @param uri - Resource URI
     * @returns Resource or undefined
     */
    get(uri: URI): InMemoryResource | undefined;
    
    /**
     * Remove resource from collection
     * @param uri - Resource URI to remove
     */
    delete(uri: URI): boolean;
    
    /**
     * Get all resources
     * @returns Array of all resources
     */
    getAll(): InMemoryResource[];
}

Untitled Resources

Support for untitled/temporary files that haven't been saved to disk.

/**
 * Resolver for untitled resources
 */
class UntitledResourceResolver implements ResourceResolver {
    resolve(uri: URI): Promise<UntitledResource>;
    canResolve(uri: URI): boolean;
}

/**
 * Untitled resource implementation
 */
class UntitledResource implements Resource {
    readonly uri: URI;
    readonly version?: ResourceVersion;
    
    constructor(uri: URI, content?: string);
    
    readContents(): Promise<string>;
    saveContents(content: string): Promise<void>;
    
    /**
     * Save to actual file URI
     * @param uri - Target file URI
     * @returns Promise that resolves when saved
     */
    saveAs(uri: URI): Promise<void>;
}

/**
 * URI scheme for untitled resources
 */
const UNTITLED_SCHEME = 'untitled';

File System Integration

File URI Utilities

Utilities for working with file system URIs.

/**
 * File URI utilities
 */
class FileUri {
    /**
     * Create file URI from path
     * @param path - File system path
     * @returns File URI
     */
    static create(path: string): URI;
    
    /**
     * Get file system path from URI
     * @param uri - File URI
     * @returns File system path
     */
    static fsPath(uri: URI): string;
    
    /**
     * Check if URI is file URI
     * @param uri - URI to check
     * @returns True if file URI
     */
    static is(uri: URI): boolean;
}

Resource Options

Configuration options for resource operations.

/**
 * Options for reading resources
 */
interface ResourceReadOptions {
    /** Text encoding */
    encoding?: string;
    
    /** Expected version */
    version?: ResourceVersion;
    
    /** Byte range to read */
    range?: {
        start: number;
        end: number;
    };
}

/**
 * Options for saving resources
 */
interface ResourceSaveOptions {
    /** Text encoding */
    encoding?: string;
    
    /** Expected current version */
    version?: ResourceVersion;
    
    /** Create parent directories */
    createParents?: boolean;
    
    /** Overwrite existing */
    overwrite?: boolean;
}

/**
 * Resource stat information
 */
interface ResourceStat {
    /** Resource URI */
    readonly uri: URI;
    
    /** Last modification time */
    readonly mtime?: number;
    
    /** File size in bytes */
    readonly size?: number;
    
    /** True if resource is directory */
    readonly isDirectory: boolean;
    
    /** True if resource is read-only */
    readonly readonly?: boolean;
}

Error Handling

Resource Errors

Standardized error types for resource operations.

/**
 * Resource error namespace
 */
namespace ResourceError {
    /**
     * Error when resource is not found
     */
    class NotFound extends Error {
        constructor(uri: URI);
        readonly uri: URI;
    }
    
    /**
     * Error when resource is out of sync
     */
    class OutOfSync extends Error {
        constructor(uri: URI, expectedVersion: ResourceVersion, actualVersion: ResourceVersion);
        readonly uri: URI;
        readonly expectedVersion: ResourceVersion;
        readonly actualVersion: ResourceVersion;
    }
    
    /**
     * Error when operation is not supported
     */
    class NotSupported extends Error {
        constructor(operation: string, uri: URI);
        readonly operation: string;
        readonly uri: URI;
    }
}

Types

/**
 * URI scheme constants
 */
const FILE_SCHEME = 'file';
const HTTP_SCHEME = 'http';
const HTTPS_SCHEME = 'https';
const MEMORY_TEXT = 'mem-txt';
const UNTITLED_SCHEME = 'untitled';

/**
 * Resource-related type aliases
 */
type ResourceChangeType = 'added' | 'updated' | 'deleted';

interface ResourceChange {
    readonly uri: URI;
    readonly type: ResourceChangeType;
}

type ResourceWatcher = {
    readonly onDidChange: Event<ResourceChange[]>;
    dispose(): void;
};

Install with Tessl CLI