@cyberismo/data-handler 0.0.14 → 0.0.16

package/dist/resources/resource-object.d.ts

@@ -9,11 +9,11 @@
     You should have received a copy of the GNU Affero General Public
     License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
+import { type ResourceName } from '../utils/resource-utils.js';
 import type { Card, ResourceFolderType } from '../interfaces/project-interfaces.js';
 import type { Logger } from 'pino';
-import { type Project } from '../containers/project.js';
-import type { ResourceContent } from '../interfaces/resource-interfaces.js';
-import type { ResourceName } from '../utils/resource-utils.js';
+import type { Project } from '../containers/project.js';
+import type { ResourceBaseMetadata, UpdateKey } from '../interfaces/resource-interfaces.js';
 export type UpdateOperations = 'add' | 'change' | 'rank' | 'remove';
 type BaseOperation<T> = {
     name: 'add' | 'change' | 'rank' | 'remove';
@@ -45,71 +45,153 @@ export type OperationMap<T> = {
     remove: RemoveOperation<T>;
 };
 export type OperationFor<T, N extends UpdateOperations> = OperationMap<T>[N];
+export type ShowReturnType<T extends ResourceBaseMetadata, U = never> = Omit<T, 'content'> & {
+    [K in 'content' as [U] extends [never] ? never : K]: U;
+};
 /**
  * Abstract class for resources.
  */
-export declare abstract class AbstractResource {
+export declare abstract class AbstractResource<T extends ResourceBaseMetadata, U = never> {
     protected abstract calculate(): Promise<void>;
-    protected abstract create(content?: ResourceContent): Promise<void>;
+    protected abstract create(content?: T): Promise<void>;
     protected abstract delete(): Promise<void>;
     protected abstract read(): Promise<void>;
     protected abstract rename(newName: ResourceName): Promise<void>;
-    protected abstract show(): Promise<ResourceContent>;
-    protected abstract update<Type>(key: string, operation: Operation<Type>): Promise<void>;
+    protected abstract show(): ShowReturnType<T, U>;
+    protected abstract update<Type, K extends string>(updateKey: UpdateKey<K>, operation: Operation<Type>): Promise<void>;
     protected abstract usage(cards?: Card[]): Promise<string[]>;
     protected abstract validate(content?: object): Promise<void>;
     protected abstract write(): Promise<void>;
     protected abstract get getType(): string;
     protected abstract getLogger(loggerName: string): Logger;
 }
-/**
- * Base class for all resources.
- */
-export declare class ResourceObject extends AbstractResource {
+export declare abstract class ResourceObject<T extends ResourceBaseMetadata, U> extends AbstractResource<T, U> {
     protected project: Project;
     protected resourceName: ResourceName;
+    private static validateInstancePromise?;
+    protected content: T;
     protected moduleResource: boolean;
     protected contentSchema: JSON;
     protected contentSchemaId: string;
     protected type: ResourceFolderType;
     protected resourceFolder: string;
-    constructor(project: Project, resourceName: ResourceName);
+    protected logger: Logger;
+    /**
+     * Path to the resource metadata file (the .json file).
+     */
+    fileName: string;
+    /**
+     * Constructs a ResourceObject instance
+     * @param project Project where this resource is
+     * @param resourceName Name for the resource
+     * @param type Type of resource
+     */
+    constructor(project: Project, resourceName: ResourceName, type: ResourceFolderType);
+    private exists;
+    private static getValidate;
+    private reportHandlerBarFiles;
+    private resourceType;
+    /**
+     * Checks if resource exists.
+     * This should only throw, if someone creates resources directly; ie. not through the cache
+     * @throws if resource does not exist
+     */
+    protected assertResourceExists(): void;
+    /**
+     * Calculate; empty implementation.
+     */
     protected calculate(): Promise<void>;
-    protected create(_content?: ResourceContent): Promise<void>;
-    protected delete(): Promise<void>;
-    protected read(): Promise<void>;
-    protected rename(_name: ResourceName): Promise<void>;
-    protected show(): Promise<ResourceContent>;
-    protected get getType(): string;
-    protected getLogger(loggerName: string): Logger;
-    protected update<Type>(_key: string, _op: Operation<Type>): Promise<void>;
-    protected usage(_cards?: Card[]): Promise<string[]>;
-    protected validate(_content?: object): Promise<void>;
-    protected write(): Promise<void>;
+    /**
+     * Calculations that use this resource.
+     * @throws if accessing calculations files failed
+     */
+    protected calculations(): Promise<string[]>;
+    /**
+     * Cards from project.
+     */
+    protected cards(): Card[];
     /**
      * Returns .schema content file.
      * @param schemaId schema id
      * @returns .schema content.
      */
     protected contentSchemaContent(schemaId: string): JSON;
+    /**
+     * Creates resource.
+     * @param newContent Content for resource.
+     * @throws when resource already exists in the project.
+     */
+    protected create(newContent?: T): Promise<void>;
+    /**
+     * Gets a logger instance.
+     * @param loggerName
+     * @returns logger instance
+     */
+    protected getLogger(loggerName: string): Logger;
+    /**
+     * Returns type of this resource.
+     */
+    protected get getType(): string;
     /**
      * Handles operation to an array.
      * @param operation Operation to perform on array.
      * @param arrayName Name of the array, for error messages.
      * @param array Array to be updated.
      * @returns Changed array after the operation.
+     * @throws when operation cannot be done.
      */
     protected handleArray<Type>(operation: Operation<Type>, arrayName: string, array: Type[]): Type[];
     /**
      * Updates scalar value. The only accepted operation is 'change'
      * @param operation Operation to perform on scalar.
      * @returns What the scalar should be changed to.
+     * @throws when operation cannot be done
      */
     protected handleScalar<Type>(operation: Operation<Type>): Type;
+    /**
+     * Initialize the resource.
+     */
+    protected initialize(): void;
+    /**
+     * Called after inherited class has finished 'update' operation.
+     * @param content New content for resource
+     * @param updateKey Which property to change
+     * @param op What kind of operation is performed to updateKey
+     * @throws if validation fails after the update
+     */
+    protected postUpdate<Type, K extends string>(content: T, updateKey: UpdateKey<K>, op: Operation<Type>): Promise<void>;
+    /**
+     * Reads content from file to memory.
+     */
+    protected read(): Promise<void>;
+    /**
+     * Renames resource.
+     * @param newName New name for the resource.
+     * @throws if trying to rename module resource, or
+     *         if resource does not exist,
+     *         if trying to rename so that type changes
+     */
+    protected rename(newName: ResourceName): Promise<void>;
+    /**
+     * Update resource; the base class makes some checks only.
+     * @template type Resource type
+     * @template K Resource key
+     * @throws if resource does not exist, or
+     *         if trying to update module content, or
+     *         if key is empty
+     */
+    protected update<Type, K extends string>(key: UpdateKey<K>, _op: Operation<Type>): Promise<void>;
+    /**
+     * Validates resource identifier to prevent filesystem operations with invalid names
+     * todo: To Validate?
+     */
+    protected validateResourceIdentifier(): void;
     /**
      * Update calculation files.
      * @param from Resource name to update
      * @param to New name for resource
+     * @throws if 'from' or 'to' is empty string, or
+     *         if there was error accessing calculation files.
      */
     protected updateCalculations(from: string, to: string): Promise<void>;
     /**
@@ -117,7 +199,45 @@ export declare class ResourceObject extends AbstractResource {
      * @param from Resource name to update
      * @param to New name for resource
      * @param handleBarFiles Optional. List of handlebar files. If omitted, affects all handlebar files in the project.
+     * @throws if 'from' or 'to' is empty string
      */
     protected updateHandleBars(from: string, to: string, handleBarFiles?: string[]): Promise<void>;
+    /**
+     * Check if there are references to the resource in the card content.
+     * @note that this needs to be async, since inherited classes need to async operations
+     * @param cards cards to check
+     * @throws if resource does not exist
+     */
+    protected usage(cards?: Card[]): Promise<string[]>;
+    /**
+     * Checks if resource name is valid.
+     * @param newName New name for resource.
+     * @returns valid name
+     */
+    protected validName(newName: ResourceName): Promise<string>;
+    /**
+     * Write the content from memory to disk.
+     * @throws if trying to write a module resource.
+     */
+    protected write(): Promise<void>;
+    /**
+     * Returns memory resident data as JSON.
+     * This is basically same as 'show' but doesn't do any checks; just returns the current content.
+     * @returns metadata content or undefined if resource does not exist.
+     */
+    get data(): T | undefined;
+    /**
+     * Deletes the file and removes the resource from project.
+     * @throws if resource is a module resource, or
+     *         if resource does not exist, or
+     *         if resource is used by other resources.
+     */
+    delete(): Promise<void>;
+    /**
+     * Validates the content of the resource.
+     * @param content Content to be validated.
+     * @throws if content is invalid.
+     */
+    validate(content?: object): Promise<void>;
 }
 export {};