@giancarl021/cli-core-vault-extension/lib/src/services/ObjectStorage.d.ts

Plain and secure storage extension for the @giancarl021/cli-core npm package

import type { FileStorageInstance } from './FileStorage.js';
/**
 * Join two string literal types with a dot.
 *
 * @template K The first part of the path.
 * @template P The second part of the path.
 */
type Join<K extends string, P extends string> = `${K}.${P}`;
/**
 * Generate all possible dot-separated paths for nested properties in an object type.
 *
 * @template T The object type to generate paths for.
 */
type Primitive = string | number | boolean | bigint | symbol | null | undefined | Date | Function | Array<any>;
type ObjectPaths<T> = T extends Primitive ? never : {
    [K in keyof T & string]: T[K] extends Primitive ? K : K | Join<K, ObjectPaths<T[K]>>;
}[keyof T & string];
type Paths<T> = ObjectPaths<T>;
/**
 * Get the type of a property (including nested) in an object type based on a dot-separated path.
 *
 * @template T The object type.
 * @template P The dot-separated path to the property.
 */
type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : undefined : P extends keyof T ? T[P] : undefined;
/**
 * JSON object storage service instance.
 */
export type ObjectStorageInstance<Schema extends object> = ReturnType<typeof ObjectStorage<Schema>>;
/**
 * JSON object storage service.
 *
 * @template Schema The schema of the object to be stored.
 * @param storage The underlying storage engine to use.
 * @param initialData Initial data to populate the storage with if empty.
 * @returns An object with methods to interact with the stored object.
 */
export default function ObjectStorage<Schema extends object>(storage: FileStorageInstance<Schema>, initialData: Schema): {
    /**
     * Set a property (including nested) of the object according to the Schema.
     *
     * @template P A property path of the Schema.
     *
     * @param prop The property path to set.
     * @param value The value to set at the specified property path.
     * @returns A promise that resolves when the property has been set.
     */
    set: <P extends Paths<Schema>>(prop: P, value: PathValue<Schema, P>) => Promise<void>;
    /**
     * Get a property (including nested) of the object according to the Schema.
     *
     * @template P A property path of the Schema.
     *
     * @param prop The property path to get.
     * @param defaultValue An optional default value to return if the property is not found.
     * @returns A promise that resolves to the value at the specified property path, or the default value if provided and the property is not found.
     */
    get: {
        <P extends Paths<Schema>>(prop: P): Promise<PathValue<Schema, P> | undefined>;
        <P extends Paths<Schema>>(prop: P, defaultValue: PathValue<Schema, P>): Promise<PathValue<Schema, P>>;
    };
    /**
     * Remove a property (including nested) of the object according to the Schema.
     *
     * @template P A property path of the Schema.
     *
     * @param prop The property path to remove.
     * @returns A promise that resolves when the property has been removed.
     */
    remove: <P extends Paths<Schema>>(prop: P) => Promise<void>;
    /**
     * List all keys (including nested) in the stored object.
     *
     * @returns A promise that resolves to an array of all keys in the object.
     */
    listKeys: () => Promise<string[]>;
    /**
     * The underlying storage engine used by the ObjectStorage.
     */
    storage: FileStorageInstance<Schema>;
};
export {};