@giancarl021/cli-core-vault-extension
Version:
Plain and secure storage extension for the @giancarl021/cli-core npm package
575 lines (574 loc) • 37.8 kB
TypeScript
/**
* The instance type returned by the FileStorage factory function.
*/
export type FileStorageInstance<Schema extends object> = ReturnType<typeof FileStorage<Schema>>;
/**
* Store data as JSON in a file on the filesystem.
* Also implements workspace functionality to isolate data for different contexts.
* Binary files can be stored using native APIs like `fs.promises.writeFile` and `fs.promises.readFile`
* in conjunction with the `getPath` method to get absolute paths without worrying about the root directory.
*
* @template Schema - The type of the data schema to be stored.
* @param rootPath The root directory where data files will be stored.
* @param lazyInitialization If `true`, the storage will only be initialized when first accessed.
* If `false`, it will be initialized immediately.
* Default is `true`.
* @param key The workspace key to isolate data. Default is `constants.workspace.defaultKey`.
* @returns An object implementing the StorageEngine interface for managing the data.
*/
export default function FileStorage<Schema extends object>(rootPath: string, lazyInitialization: boolean, key?: string): {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: Schema) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: Schema) => Promise<Schema>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
/**
* Create a new workspace with the given key.
* @param key The key to create a unique workspace directory.
* @returns A new FileStorage instance for the specified workspace.
*/
createWorkspace: <WorkspaceSchema extends object = Schema>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema) => Promise<WorkspaceSchema>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_1 extends object = WorkspaceSchema>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_1) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_1) => Promise<WorkspaceSchema_1>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_2 extends object = WorkspaceSchema_1>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_2) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_2) => Promise<WorkspaceSchema_2>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_3 extends object = WorkspaceSchema_2>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_3) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_3) => Promise<WorkspaceSchema_3>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_4 extends object = WorkspaceSchema_3>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_4) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_4) => Promise<WorkspaceSchema_4>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_5 extends object = WorkspaceSchema_4>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_5) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_5) => Promise<WorkspaceSchema_5>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_6 extends object = WorkspaceSchema_5>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_6) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_6) => Promise<WorkspaceSchema_6>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_7 extends object = WorkspaceSchema_6>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_7) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_7) => Promise<WorkspaceSchema_7>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_8 extends object = WorkspaceSchema_7>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_8) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_8) => Promise<WorkspaceSchema_8>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_9 extends object = WorkspaceSchema_8>(key: string) => {
/**
* Writes the given value as JSON to the file. It must follow the Schema type.
* @param path The relative path within the workspace to write the object to.
* @param value The object to serialize and write.
* @returns A promise that resolves when the write is complete.
*/
writeObject: (path: string, value: WorkspaceSchema_9) => Promise<void>;
/**
* Reads and parses a JSON object from the file. If the file does not exist,
* it will be created with the provided default value.
* @param path The relative path within the workspace to read the object from.
* @param defaultValue The default value to write and return if the file does not exist.
* @returns A promise that resolves to the parsed object.
*/
readObject: (path: string, defaultValue: WorkspaceSchema_9) => Promise<WorkspaceSchema_9>;
/**
* Removes the file at the specified relative path within the workspace. If the file does not exist,
* no action is taken.
* @param path The relative path within the workspace to remove the object from.
* @returns A promise that resolves when the file is removed.
*/
removeObject: (path: string) => Promise<void>;
/**
* Get the root path of the storage.
* @returns The absolute path to the root directory.
*/
getRootPath: () => string;
/**
* Get the workspace path (root path + workspace).
* @returns The absolute path to the root directory for the current workspace.
*/
getWorkspacePath: () => string;
/**
* Get the absolute path for a given relative path within the storage root.
* @param relativePath The relative path to resolve.
* @returns The absolute path.
*/
getPath: (relativePath: string) => string;
/**
* Destroys the entire storage by removing the root directory and all its contents.
* @returns A promise that resolves when the storage is destroyed.
*/
destroy: () => Promise<void>;
createWorkspace: <WorkspaceSchema_10 extends object = WorkspaceSchema_9>(key: string) => /*elided*/ any;
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};
/**
* Destroy the current workspace by removing its directory and all its contents.
* @returns A promise that resolves when the workspace is destroyed.
*/
destroyWorkspace: () => Promise<void>;
};