@theia/workspace/lib/browser/metadata-storage/workspace-metadata-storage-service.d.ts

Theia - Workspace Extension

/********************************************************************************
 * Copyright (C) 2026 EclipseSource and others.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the Eclipse
 * Public License v. 2.0 are satisfied: GNU General Public License, version 2
 * with the GNU Classpath Exception which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 ********************************************************************************/
import { FileService } from '@theia/filesystem/lib/browser/file-service';
import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
import { ILogger } from '@theia/core/lib/common/logger';
import { URI } from '@theia/core/lib/common/uri';
import { WorkspaceService } from '../workspace-service';
import { WorkspaceMetadataStore, WorkspaceMetadataStoreImpl } from './workspace-metadata-store';
export declare const WorkspaceMetadataStoreFactory: unique symbol;
export type WorkspaceMetadataStoreFactory = () => WorkspaceMetadataStoreImpl;
/**
 * Index mapping workspace root paths to UUIDs.
 * Stored at $CONFIGDIR/workspace-metadata/index.json
 */
export interface WorkspaceMetadataIndex {
    [workspacePath: string]: string;
}
/**
 * Service for managing workspace-specific metadata storage.
 * Provides isolated storage directories for different features within a workspace.
 *
 * This is different to the `WorkspaceStorageService` in that it is an unlimited free-form
 * storage area _in the filesystem_ and not in the browser's local storage.
 */
export declare const WorkspaceMetadataStorageService: unique symbol;
export interface WorkspaceMetadataStorageService {
    /**
     * Gets an existing metadata store for the given key, or creates a new one if it doesn't exist.
     *
     * @param key A unique identifier for the metadata store. Special characters will be replaced with hyphens.
     * @returns The existing or newly created WorkspaceMetadataStore instance
     * @throws Error if no workspace is currently open
     */
    getOrCreateStore(key: string): Promise<WorkspaceMetadataStore>;
}
export declare class WorkspaceMetadataStorageServiceImpl implements WorkspaceMetadataStorageService {
    protected readonly fileService: FileService;
    protected readonly workspaceService: WorkspaceService;
    protected readonly envVariableServer: EnvVariablesServer;
    protected readonly logger: ILogger;
    protected readonly storeFactory: WorkspaceMetadataStoreFactory;
    /**
     * Registry of created stores by their mangled keys
     */
    protected readonly stores: Map<string, WorkspaceMetadataStore>;
    /**
     * Cached metadata root directory (e.g., file://$CONFIGDIR/workspace-metadata/)
     */
    protected metadataRoot?: URI;
    /**
     * Cached index file location
     */
    protected indexFile?: URI;
    getOrCreateStore(key: string): Promise<WorkspaceMetadataStore>;
    protected doCreateStore(key: string, mangledKey: string): Promise<WorkspaceMetadataStore>;
    /**
     * Mangles a key to make it safe for use as a directory name.
     * Replaces all characters except alphanumerics, hyphens, and underscores with hyphens.
     */
    protected mangleKey(key: string): string;
    protected getFirstWorkspaceRoot(): URI | undefined;
    /**
     * Gets or creates a UUID for the given workspace root.
     * UUIDs are stored in an index file and reused if the same workspace is opened again.
     */
    protected getOrCreateWorkspaceUUID(workspaceRoot: URI): Promise<string>;
    protected loadIndex(): Promise<WorkspaceMetadataIndex>;
    protected saveIndex(index: WorkspaceMetadataIndex): Promise<void>;
    protected getMetadataRoot(): Promise<URI>;
    protected getIndexFile(): Promise<URI>;
    /**
     * Gets the location for a store given a workspace UUID and mangled key.
     */
    protected getStoreLocation(workspaceUuid: string, mangledKey: string): Promise<URI>;
    /**
     * Resolves the current store location for a given mangled key.
     * Used when workspace changes to get the new location.
     */
    protected resolveStoreLocation(mangledKey: string): Promise<URI>;
}
//# sourceMappingURL=workspace-metadata-storage-service.d.ts.map