@cyberismo/data-handler 0.0.15 → 0.0.16

package/dist/containers/project/resource-cache.d.ts

@@ -0,0 +1,169 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  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 { CalculationResource } from '../../resources/calculation-resource.js';
+import { CardTypeResource } from '../../resources/card-type-resource.js';
+import { FieldTypeResource } from '../../resources/field-type-resource.js';
+import { GraphModelResource } from '../../resources/graph-model-resource.js';
+import { GraphViewResource } from '../../resources/graph-view-resource.js';
+import { LinkTypeResource } from '../../resources/link-type-resource.js';
+import { ReportResource } from '../../resources/report-resource.js';
+import { TemplateResource } from '../../resources/template-resource.js';
+import { WorkflowResource } from '../../resources/workflow-resource.js';
+import type { Project } from '../project.js';
+import type { ResourceFolderType } from '../../interfaces/project-interfaces.js';
+import type { ResourceName } from '../../utils/resource-utils.js';
+export interface Resource {
+    name: string;
+    path: string;
+}
+export type ResourceMap = {
+    calculations: CalculationResource;
+    cardTypes: CardTypeResource;
+    fieldTypes: FieldTypeResource;
+    graphViews: GraphViewResource;
+    graphModels: GraphModelResource;
+    linkTypes: LinkTypeResource;
+    reports: ReportResource;
+    templates: TemplateResource;
+    workflows: WorkflowResource;
+};
+export type ExtractResourceType<T extends string> = T extends `${string}/${infer R}/${string}` ? R : never;
+export type SafeExtract<T extends string> = ExtractResourceType<T> extends keyof ResourceMap ? ExtractResourceType<T> : never;
+export declare enum ResourcesFrom {
+    all = "all",
+    importedOnly = "imported",
+    localOnly = "local"
+}
+/**
+ * ResourceCache handles all resource collecting, caching, and management.
+ * Uses a two-layered approach:
+ *  1. lightweight registry for collecting items that exist on disk
+ *  2. more complex instance cache that contains full instance data of a resource.
+ *
+ * Resource populates the first layer automatically when created.
+ * When new instance of a resource is created by an access function (e.g. resourceByType() or resourceByName()),
+ * instance of resource is saved to cache.
+ *
+ */
+export declare class ResourceCache {
+    private resourceRegistry;
+    private instanceCache;
+    private project;
+    private constructor();
+    private initialize;
+    private buildResourceName;
+    private createResourceObject;
+    private collectAllResources;
+    private collectLocalResources;
+    private collectModuleResources;
+    private collectResourceContentFiles;
+    private collectResourcesOfType;
+    private deleteKey;
+    private hasSetContentFiles;
+    private static get logger();
+    private normalizeResourceName;
+    /**
+     * Add a resource instance to cache. If using
+     * @param name Name of the resource to update
+     * @param instance New data for the resource.
+     */
+    addResource(name: string | ResourceName, instance: unknown): void;
+    /**
+     * Refresh local resources in the cache.
+     */
+    changed(): void;
+    /**
+     * Refresh module resources in the cache.
+     * @param moduleName Name of the module. If given, will only update this modules resources.
+     */
+    changedModules(moduleName?: string): void;
+    /**
+     * Change resource name in cache, but keep instance information.
+     * Cache has to create cache key for new and move the existing instance to it.
+     * @param oldName Old name of the resource
+     * @param newName New name of the resource
+     */
+    changeResourceName(oldName: string, newName: string): void;
+    /**
+     * Creates and initializes a ResourceCache.
+     * This performs filesystem I/O to collect all resources.
+     * @param project Project to use
+     * @returns Initialized ResourceCache
+     */
+    static create(project: Project): ResourceCache;
+    /**
+     * Handle file system changes
+     * This is used by the Watcher in the Project class.
+     * @param fileName A changed file in the file system.
+     */
+    handleFileSystemChange(fileName: string): void;
+    /**
+     * Invalidate a resource instance.
+     * This forces reload on next access.
+     * @param name Name of the resource to invalidate.
+     */
+    invalidateResource(name: string | ResourceName): void;
+    /**
+     * Get module names.
+     * @returns Module names.
+     */
+    moduleNames(): string[];
+    /**
+     * Get certain types of resources from a specific module.
+     * @param type Type of resource to fetch
+     * @param moduleName Name of the module
+     * @returns resources names from a specific module.
+     */
+    moduleResourceNames(type: ResourceFolderType, moduleName: string): string[];
+    /**
+     * Invalidate all resources of a specific module.
+     * @param moduleName Name of the module.
+     */
+    removeModule(moduleName: string): void;
+    /**
+     * Remove a resource from cache. This includes both registry and instance cache.
+     * @param name Resource to remove.
+     */
+    removeResource(name: string | ResourceName): void;
+    /**
+     * Get resource with explicit type parameter
+     * @param name Name of the resource
+     * @param type Type of the resource
+     * @template T Resource type
+     * @throws If resource creation fails.
+     * @returns Typed resource that matches name and type.
+     */
+    resourceByType<T extends keyof ResourceMap>(name: string, type: T): ResourceMap[T];
+    /**
+     * Get resource by ResourceName object
+     * @param name Resource name.
+     * @throws If resource creation fails.
+     * @returns Typed resource that matches the name.
+     */
+    resourceByName<T extends keyof ResourceMap>(name: ResourceName): ResourceMap[T];
+    /**
+     * Check if a resource exists.
+     * @param name Resource name to check.
+     * @returns true, if resource is in the cache; false otherwise.
+     */
+    has(name: string | ResourceName): boolean;
+    /**
+     * Get resources with full metadata for a specific type
+     * @param type Type of resources to get.
+     * @param from Where to return resources from (all, local, imported modules)
+     * @template T Resource type
+     * @returns Array of resources with metadata.
+     */
+    resources<T extends keyof ResourceMap>(type: T, from?: ResourcesFrom): Array<ResourceMap[T]>;
+}

package/dist/containers/project/resource-cache.js

@@ -0,0 +1,507 @@
+/**
+  Cyberismo
+  Copyright © Cyberismo Ltd and contributors 2025
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU Affero General Public License version 3 as published by
+  the Free Software Foundation. This program is distributed in the hope that it
+  will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU Affero General Public License for more details.
+  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 { dirname, extname, join } from 'node:path';
+import { readdirSync, readFileSync } from 'node:fs';
+import { getChildLogger } from '../../utils/log-utils.js';
+import { pathToResourceName, resourceName, resourceNameToString, } from '../../utils/resource-utils.js';
+import { stripExtension } from '../../utils/file-utils.js';
+import { VALID_FOLDER_RESOURCE_FILES } from '../../utils/constants.js';
+import { CalculationResource } from '../../resources/calculation-resource.js';
+import { CardTypeResource } from '../../resources/card-type-resource.js';
+import { FieldTypeResource } from '../../resources/field-type-resource.js';
+import { GraphModelResource } from '../../resources/graph-model-resource.js';
+import { GraphViewResource } from '../../resources/graph-view-resource.js';
+import { LinkTypeResource } from '../../resources/link-type-resource.js';
+import { ReportResource } from '../../resources/report-resource.js';
+import { TemplateResource } from '../../resources/template-resource.js';
+import { WorkflowResource } from '../../resources/workflow-resource.js';
+// Defines where resources are collected from.
+export var ResourcesFrom;
+(function (ResourcesFrom) {
+    ResourcesFrom["all"] = "all";
+    ResourcesFrom["importedOnly"] = "imported";
+    ResourcesFrom["localOnly"] = "local";
+})(ResourcesFrom || (ResourcesFrom = {}));
+// Allowed files in resource instance data.
+const allowedExtensions = ['.lp', '.json'];
+// Resource types that have internal folders with content files
+const FOLDER_RESOURCE_TYPES = [
+    'calculations',
+    'graphModels',
+    'graphViews',
+    'reports',
+    'templates',
+];
+/**
+ * ResourceCache handles all resource collecting, caching, and management.
+ * Uses a two-layered approach:
+ *  1. lightweight registry for collecting items that exist on disk
+ *  2. more complex instance cache that contains full instance data of a resource.
+ *
+ * Resource populates the first layer automatically when created.
+ * When new instance of a resource is created by an access function (e.g. resourceByType() or resourceByName()),
+ * instance of resource is saved to cache.
+ *
+ */
+export class ResourceCache {
+    resourceRegistry = new Map();
+    instanceCache = new Map();
+    project;
+    // Private constructor - use ResourceCache.create() instead.
+    constructor(project) {
+        this.project = project;
+    }
+    // Initialize the cache by collecting all resources.
+    initialize() {
+        this.collectAllResources();
+    }
+    // Build a full resource name from partial name and type.
+    buildResourceName(name, type) {
+        if (type && name && name.split('/').length === 1) {
+            name = `${this.project.projectPrefix}/${type}/${name}`;
+        }
+        return resourceName(name);
+    }
+    // Create a resource object instance
+    createResourceObject(resourceName) {
+        const key = resourceNameToString(resourceName);
+        const metadata = this.resourceRegistry.get(key);
+        let resource;
+        if (resourceName.type === 'calculations') {
+            resource = new CalculationResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'cardTypes') {
+            resource = new CardTypeResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'fieldTypes') {
+            resource = new FieldTypeResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'graphModels') {
+            resource = new GraphModelResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'graphViews') {
+            resource = new GraphViewResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'linkTypes') {
+            resource = new LinkTypeResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'reports') {
+            resource = new ReportResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'templates') {
+            resource = new TemplateResource(this.project, resourceName);
+        }
+        else if (resourceName.type === 'workflows') {
+            resource = new WorkflowResource(this.project, resourceName);
+        }
+        else {
+            throw new Error(`Unsupported resource type '${resourceName.type}'`);
+        }
+        // Populate content files into folder resources
+        if (metadata?.contentFiles && this.hasSetContentFiles(resource)) {
+            resource.setContentFiles(metadata.contentFiles);
+        }
+        return resource;
+    }
+    // Collects all resources; both local and modules.
+    collectAllResources() {
+        this.collectLocalResources();
+        this.collectModuleResources();
+    }
+    // Collect all local resources from the filesystem
+    collectLocalResources() {
+        const resourceTypes = [
+            'calculations',
+            'cardTypes',
+            'fieldTypes',
+            'graphModels',
+            'graphViews',
+            'linkTypes',
+            'reports',
+            'templates',
+            'workflows',
+        ];
+        for (const type of resourceTypes) {
+            this.collectResourcesOfType(type, 'local');
+        }
+    }
+    // Collect all module resources from the filesystem
+    // Only collects modules that are registered in the project configuration
+    // todo: For future:
+    // Should it also try to collect what is in .local/modules and then log for disparities?
+    collectModuleResources() {
+        try {
+            const registeredModules = this.project.configuration.modules.map((m) => m.name);
+            if (registeredModules.length === 0) {
+                return;
+            }
+            const resourceTypes = [
+                'calculations',
+                'cardTypes',
+                'fieldTypes',
+                'graphModels',
+                'graphViews',
+                'linkTypes',
+                'reports',
+                'templates',
+                'workflows',
+            ];
+            for (const moduleName of registeredModules) {
+                for (const type of resourceTypes) {
+                    this.collectResourcesOfType(type, 'module', moduleName);
+                }
+            }
+        }
+        catch {
+            ResourceCache.logger.warn(`.cards/modules folder is missing`);
+        }
+    }
+    // Collects one folder resource's internal folder content.
+    collectResourceContentFiles(type, entry) {
+        const identifier = stripExtension(entry.name);
+        let contentFiles = undefined;
+        // Set content files for folder resources
+        if (FOLDER_RESOURCE_TYPES.includes(type)) {
+            const internalFolder = join(entry.parentPath, identifier);
+            try {
+                const contentEntries = readdirSync(internalFolder, {
+                    withFileTypes: true,
+                });
+                const files = new Map();
+                for (const contentEntry of contentEntries) {
+                    if (contentEntry.isFile() &&
+                        VALID_FOLDER_RESOURCE_FILES.includes(contentEntry.name)) {
+                        try {
+                            const filePath = join(internalFolder, contentEntry.name);
+                            const content = readFileSync(filePath, 'utf8');
+                            files.set(contentEntry.name, content);
+                        }
+                        catch {
+                            ResourceCache.logger.warn(`Failed to read content file '${contentEntry.name}' for resource '${name}'`);
+                        }
+                    }
+                }
+                contentFiles = files.size > 0 ? files : undefined;
+            }
+            catch {
+                // Internal folder doesn't exist - this is okay
+            }
+        }
+        return contentFiles;
+    }
+    // Collect resources of a specific type
+    collectResourcesOfType(type, source, moduleName) {
+        const resourceFolder = source === 'local'
+            ? this.project.paths.resourcePath(type)
+            : join(this.project.paths.modulesFolder, moduleName, type);
+        try {
+            const entries = readdirSync(resourceFolder, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile() && allowedExtensions.includes(extname(entry.name))) {
+                    const name = source === 'local'
+                        ? `${this.project.projectPrefix}/${type}/${stripExtension(entry.name)}`
+                        : `${moduleName}/${type}/${stripExtension(entry.name)}`;
+                    this.resourceRegistry.set(name, {
+                        name: name,
+                        type: type,
+                        path: entry.parentPath,
+                        source: source,
+                        moduleName: source === 'module' ? moduleName : undefined,
+                        contentFiles: this.collectResourceContentFiles(type, entry),
+                    });
+                }
+            }
+        }
+        catch {
+            ResourceCache.logger.warn(`Resource folder '${resourceFolder}' is missing`);
+        }
+    }
+    // Removes a key from cache layers.
+    deleteKey(key) {
+        this.resourceRegistry.delete(key);
+        this.instanceCache.delete(key);
+    }
+    // Type guard to check if resource has setContentFiles method
+    hasSetContentFiles(resource) {
+        return (typeof resource.setContentFiles ===
+            'function');
+    }
+    // Returns instance of logger.
+    static get logger() {
+        return getChildLogger({
+            module: 'resourceCache',
+        });
+    }
+    // Normalize resource name (string or ResourceName) to a consistent string format.
+    normalizeResourceName(name) {
+        if (typeof name === 'string') {
+            const resName = resourceName(name);
+            return resourceNameToString(resName);
+        }
+        return resourceNameToString(name);
+    }
+    /**
+     * Add a resource instance to cache. If using
+     * @param name Name of the resource to update
+     * @param instance New data for the resource.
+     */
+    addResource(name, instance) {
+        const key = this.normalizeResourceName(name);
+        if (!this.resourceRegistry.has(key)) {
+            const resName = typeof name === 'string' ? resourceName(name) : name;
+            const isModule = resName.prefix !== this.project.projectPrefix;
+            const resourcePath = isModule
+                ? this.project.paths.moduleResourcePath(resName.prefix, resName.type)
+                : this.project.paths.resourcePath(resName.type);
+            this.resourceRegistry.set(key, {
+                name: key,
+                type: resName.type,
+                path: resourcePath,
+                source: isModule ? 'module' : 'local',
+                moduleName: isModule ? resName.prefix : undefined,
+                contentFiles: undefined, // resources will set this as-needed
+            });
+            this.instanceCache.set(key, instance);
+        }
+    }
+    /**
+     * Refresh local resources in the cache.
+     */
+    changed() {
+        for (const [key, metadata] of this.resourceRegistry) {
+            if (metadata.source === 'local') {
+                this.resourceRegistry.delete(key);
+            }
+        }
+        this.collectLocalResources();
+    }
+    /**
+     * Refresh module resources in the cache.
+     * @param moduleName Name of the module. If given, will only update this modules resources.
+     */
+    changedModules(moduleName) {
+        for (const [key, metadata] of this.resourceRegistry) {
+            if (metadata.source === 'module' &&
+                (metadata.moduleName === moduleName || !moduleName)) {
+                this.resourceRegistry.delete(key);
+            }
+        }
+        this.collectModuleResources();
+    }
+    /**
+     * Change resource name in cache, but keep instance information.
+     * Cache has to create cache key for new and move the existing instance to it.
+     * @param oldName Old name of the resource
+     * @param newName New name of the resource
+     */
+    changeResourceName(oldName, newName) {
+        const oldKey = this.normalizeResourceName(oldName);
+        const newKey = this.normalizeResourceName(newName);
+        // Move instance from old key to new key if it exists
+        if (this.instanceCache.has(oldKey)) {
+            const resource = this.instanceCache.get(oldKey);
+            this.instanceCache.delete(oldKey);
+            this.instanceCache.set(newKey, resource);
+        }
+        // Update registry
+        const metadata = this.resourceRegistry.get(oldKey);
+        if (metadata) {
+            this.resourceRegistry.delete(oldKey);
+            this.resourceRegistry.set(newKey, {
+                ...metadata,
+                name: newKey,
+            });
+        }
+    }
+    /**
+     * Creates and initializes a ResourceCache.
+     * This performs filesystem I/O to collect all resources.
+     * @param project Project to use
+     * @returns Initialized ResourceCache
+     */
+    static create(project) {
+        const cache = new ResourceCache(project);
+        cache.initialize();
+        return cache;
+    }
+    /**
+     * Handle file system changes
+     * This is used by the Watcher in the Project class.
+     * @param fileName A changed file in the file system.
+     */
+    handleFileSystemChange(fileName) {
+        try {
+            const resource = pathToResourceName(this.project, fileName);
+            if (!resource) {
+                return;
+            }
+            const name = resourceNameToString(resource);
+            // Update registry with new path
+            const isModule = resource.prefix !== this.project.projectPrefix;
+            this.resourceRegistry.set(name, {
+                name: name,
+                type: resource.type,
+                path: dirname(fileName),
+                source: isModule ? 'module' : 'local',
+                moduleName: isModule ? resource.prefix : undefined,
+                contentFiles: undefined,
+            });
+            // Invalidate cached instance
+            this.invalidateResource(name);
+        }
+        catch {
+            ResourceCache.logger.warn(`Not a resource file: ${fileName}`);
+        }
+    }
+    /**
+     * Invalidate a resource instance.
+     * This forces reload on next access.
+     * @param name Name of the resource to invalidate.
+     */
+    invalidateResource(name) {
+        const key = this.normalizeResourceName(name);
+        // Remove from instance cache, but keep in registry
+        this.instanceCache.delete(key);
+    }
+    /**
+     * Get module names.
+     * @returns Module names.
+     */
+    moduleNames() {
+        const names = new Set();
+        for (const [, metadata] of this.resourceRegistry) {
+            if (metadata.source === 'module' && metadata.moduleName) {
+                names.add(metadata.moduleName);
+            }
+        }
+        return Array.from(names);
+    }
+    /**
+     * Get certain types of resources from a specific module.
+     * @param type Type of resource to fetch
+     * @param moduleName Name of the module
+     * @returns resources names from a specific module.
+     */
+    moduleResourceNames(type, moduleName) {
+        const names = [];
+        for (const [key, metadata] of this.resourceRegistry) {
+            if (metadata.type === type &&
+                metadata.source === 'module' &&
+                metadata.moduleName === moduleName) {
+                names.push(key);
+            }
+        }
+        return names;
+    }
+    /**
+     * Invalidate all resources of a specific module.
+     * @param moduleName Name of the module.
+     */
+    removeModule(moduleName) {
+        for (const [key, metadata] of this.resourceRegistry) {
+            if (metadata &&
+                metadata.source === 'module' &&
+                metadata.moduleName === moduleName) {
+                this.removeResource(key);
+            }
+        }
+    }
+    /**
+     * Remove a resource from cache. This includes both registry and instance cache.
+     * @param name Resource to remove.
+     */
+    removeResource(name) {
+        const key = this.normalizeResourceName(name);
+        if (!this.resourceRegistry.get(key)) {
+            return;
+        }
+        this.deleteKey(key);
+    }
+    /**
+     * Get resource with explicit type parameter
+     * @param name Name of the resource
+     * @param type Type of the resource
+     * @template T Resource type
+     * @throws If resource creation fails.
+     * @returns Typed resource that matches name and type.
+     */
+    resourceByType(name, type) {
+        const builtName = this.buildResourceName(name, type);
+        const key = resourceNameToString(builtName);
+        if (this.instanceCache.has(key)) {
+            return this.instanceCache.get(key);
+        }
+        const resource = this.createResourceObject(builtName);
+        if (!resource) {
+            throw new Error(`Failed to create resource '${key}'`);
+        }
+        if (this.resourceRegistry.has(key)) {
+            this.instanceCache.set(key, resource);
+        }
+        return resource;
+    }
+    /**
+     * Get resource by ResourceName object
+     * @param name Resource name.
+     * @throws If resource creation fails.
+     * @returns Typed resource that matches the name.
+     */
+    resourceByName(name) {
+        const key = resourceNameToString(name);
+        if (this.instanceCache.has(key)) {
+            return this.instanceCache.get(key);
+        }
+        const resource = this.createResourceObject(name);
+        if (!resource) {
+            throw new Error(`Failed to create resource '${key}'`);
+        }
+        if (this.resourceRegistry.has(key)) {
+            this.instanceCache.set(key, resource);
+        }
+        return resource;
+    }
+    /**
+     * Check if a resource exists.
+     * @param name Resource name to check.
+     * @returns true, if resource is in the cache; false otherwise.
+     */
+    has(name) {
+        const key = this.normalizeResourceName(name);
+        return this.resourceRegistry.has(key);
+    }
+    /**
+     * Get resources with full metadata for a specific type
+     * @param type Type of resources to get.
+     * @param from Where to return resources from (all, local, imported modules)
+     * @template T Resource type
+     * @returns Array of resources with metadata.
+     */
+    resources(type, from = ResourcesFrom.all) {
+        const resources = [];
+        for (const [key, metadata] of this.resourceRegistry) {
+            if (metadata.type !== type)
+                continue;
+            if (from === ResourcesFrom.localOnly && metadata.source !== 'local')
+                continue;
+            if (from === ResourcesFrom.importedOnly && metadata.source !== 'module')
+                continue;
+            // Get or create the actual resource instance
+            const resName = resourceName(key);
+            const resource = this.resourceByName(resName);
+            resources.push(resource);
+        }
+        return resources;
+    }
+}
+//# sourceMappingURL=resource-cache.js.map