jitar 0.1.0

package/src/runtime/Runtime.ts

@@ -0,0 +1,47 @@
+
+import HealthCheck from './interfaces/HealthCheck.js';
+
+export default abstract class Runtime
+{
+    #url?: string;
+    #healthChecks: Map<string, HealthCheck> = new Map();
+
+    constructor(url?: string)
+    {
+        this.#url = url;
+    }
+
+    get url() { return this.#url; }
+
+    addHealthCheck(name: string, healthCheck: HealthCheck): void
+    {
+        this.#healthChecks.set(name, healthCheck);
+    }
+
+    async isHealthy(): Promise<boolean>
+    {
+        for (const healthCheck of this.#healthChecks.values())
+        {
+            if (await healthCheck.isHealthy() === false)
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    async getHealth(): Promise<Map<string, boolean>>
+    {
+        const health: Map<string, boolean> = new Map();
+
+        for (const [name, healthCheck] of this.#healthChecks)
+        {
+            const healthy = await healthCheck.isHealthy();
+
+            health.set(name, healthy);
+        }
+
+        return health;
+    }
+}

package/src/runtime/caching/CacheBuilder.ts

@@ -0,0 +1,424 @@
+
+import Component from '../../core/types/Component.js';
+import Module from '../../core/types/Module.js';
+import * as AccessLevel from '../../core/definitions/AccessLevel.js';
+import Version from '../../core/Version.js';
+
+import FileManager from '../interfaces/FileManager.js';
+import ModuleLoader from '../utils/ModuleLoader.js';
+import ModuleAnalyser from '../utils/ModuleAnalyser.js';
+
+import SourceAppender from './SourceAppender.js';
+import ImportRewriter from './ImportRewriter.js';
+import RemoteBuilder from './RemoteBuilder.js';
+
+import SegmentFile from './types/SegmentFile.js';
+import SegmentImports from './types/SegmentImports.js';
+
+import ApplicationModule from './models/ApplicationModule.js';
+import Procedure from './models/Procedure.js';
+import Segment from './models/Segment.js';
+import SegmentModule from './models/SegmentModule.js';
+import Implementation from './models/Implementation.js';
+
+import SegmentFileNotLoaded from './errors/SegmentFileNotLoaded.js';
+import SegmentModuleNotLoaded from './errors/SegmentModuleNotLoaded.js';
+import MissingModuleExport from './errors/MissingModuleExport.js';
+import InvalidSegmentFilename from './errors/InvalidSegmentFilename.js';
+
+const IGNORED_SOURCE_FILES = ['.min.js'];
+
+const DEFAULT_ACCESS_LEVEL = AccessLevel.PRIVATE;
+const DEFAULT_VERSION_NUMBER = Version.DEFAULT.toString();
+
+export default class CacheBuilder
+{
+    #sourceManager: FileManager;
+    #cacheManager: FileManager;
+
+    constructor(sourceManager: FileManager, cacheManager: FileManager)
+    {
+        this.#sourceManager = sourceManager;
+        this.#cacheManager = cacheManager;
+    }
+
+    async build(segmentFiles: string[], moduleFiles: string[]): Promise<void>
+    {
+        const applicationFiles = this.#filterApplicationFiles(moduleFiles);
+
+        const segments = await this.#createSegments(segmentFiles);
+        const applicationModules = await this.#createApplicationModules(applicationFiles);
+
+        await this.#buildSegmentCache(segments);
+        await this.#buildApplicationCache(applicationModules);
+    }
+
+    #filterApplicationFiles(fileNames: string[]): string[]
+    {
+        return fileNames.filter(filename => this.#mustIgnoreFile(filename) === false);
+    }
+
+    #mustIgnoreFile(filename: string): boolean
+    {
+        return IGNORED_SOURCE_FILES.some((ignored) => filename.endsWith(ignored));
+    }
+
+    async #createSegments(filenames: string[]): Promise<Segment[]>
+    {
+        const promises = filenames.map(async (filename) => this.#createSegment(filename));
+
+        return Promise.all(promises).then(segments => segments);
+    }
+
+    async #createSegment(filename: string): Promise<Segment>
+    {
+        const definition = await this.#loadSegmentDefinition(filename);
+        const modules = await this.#createSegmentModules(definition);
+        const procedures = this.#createSegmentProcedures(modules);
+
+        return new Segment(filename, modules, procedures);
+    }
+
+    async #loadSegmentDefinition(filename: string): Promise<SegmentFile>
+    {
+        try
+        {
+            const content = await this.#sourceManager.getContent(filename);
+
+            return JSON.parse(content.toString()) as SegmentFile;
+        }
+        catch (error: unknown)
+        {
+            throw new SegmentFileNotLoaded(filename);
+        }
+    }
+
+    async #createSegmentModules(definition: SegmentFile): Promise<SegmentModule[]>
+    {
+        const modules: SegmentModule[] = [];
+
+        for (const [moduleFilename, moduleImports] of Object.entries(definition))
+        {
+            const absoluteLocation = this.#sourceManager.getAbsoluteLocation(moduleFilename);
+            const module = await this.#createSegmentModule(absoluteLocation, moduleImports);
+
+            modules.push(module);
+        }
+
+        return modules;
+    }
+
+    async #createSegmentModule(absoluteLocation: string, imports: SegmentImports): Promise<SegmentModule>
+    {
+        const exports = await this.#loadSegmentModule(absoluteLocation);
+        const implementations = await this.#createSegmentModuleImplementations(absoluteLocation, exports, imports);
+
+        return new SegmentModule(absoluteLocation, exports, implementations);
+    }
+
+    async #loadSegmentModule(absoluteLocation: string): Promise<Module>
+    {
+        const module = await this.#loadModule(absoluteLocation);
+
+        if (module === undefined)
+        {
+            throw new SegmentModuleNotLoaded(absoluteLocation);
+        }
+
+        return module;
+    }
+
+    async #createSegmentModuleImplementations(absoluteLocation: string, exports: Module, imports: SegmentImports): Promise<Map<string, Implementation>>
+    {
+        const moduleName = this.#extractModuleName(absoluteLocation);
+        const implementations: Map<string, Implementation> = new Map();
+
+        for (const [importKey, properties] of Object.entries(imports))
+        {
+            const executable = exports[importKey] as Component;
+
+            if (executable === undefined)
+            {
+                throw new MissingModuleExport(moduleName, importKey);
+            }
+
+            const procedureName = properties.as ?? executable.name;
+            const access = properties.access ?? DEFAULT_ACCESS_LEVEL;
+            const version = properties.version ?? DEFAULT_VERSION_NUMBER;
+
+            const implementation = new Implementation(moduleName, procedureName, access, version, executable);
+
+            implementations.set(importKey, implementation);
+        }
+
+        return implementations;
+    }
+
+    #createSegmentProcedures(modules: SegmentModule[]): Map<string, Procedure>
+    {
+        const procedures = new Map<string, Procedure>();
+
+        for (const module of modules)
+        {
+            for (const implementation of module.implementations.values())
+            {
+                let procedure = procedures.get(implementation.fqn);
+
+                if (procedure === undefined)
+                {
+                    procedure = new Procedure(implementation.module, implementation.name);
+
+                    procedures.set(implementation.fqn, procedure);
+                }
+
+                procedure.addImplementation(implementation);
+            }
+        }
+
+        return procedures;
+    }
+
+    #extractModuleName(absoluteLocation: string): string
+    {
+        const relativeLocation = this.#sourceManager.getRelativeLocation(absoluteLocation);
+
+        const moduleParts = relativeLocation.split('/');
+        moduleParts.pop();
+
+        return moduleParts.join('/');
+    }
+
+    async #createApplicationModules(filenames: string[]): Promise<ApplicationModule[]>
+    {
+        const promises = filenames.map(async (filename) => this.#createApplicationModule(filename));
+
+        return Promise.all(promises).then(results => results);
+    }
+
+    async #createApplicationModule(filename: string): Promise<ApplicationModule>
+    {
+        const module = await this.#loadModule(filename);
+        const relativeLocation = this.#sourceManager.getRelativeLocation(filename);
+
+        if (module === undefined)
+        {
+            return new ApplicationModule(relativeLocation, new Map(), new Map());
+        }
+
+        const classes = ModuleAnalyser.filterClasses(module);
+        const functions = ModuleAnalyser.filterFunctions(module);
+
+        return new ApplicationModule(relativeLocation, classes, functions);
+    }
+
+    async #loadModule(filename: string): Promise<Module | undefined>
+    {
+        try
+        {
+            return await ModuleLoader.load(filename);
+        }
+        catch (error: unknown)
+        {
+            // If the module cannot load in this context it does not mean that the module is corrupted.
+            // Therefore we can ignore the error and continue to let it work (or fail) at runtime.
+
+            return undefined;
+        }
+    }
+
+    async #buildSegmentCache(segments: Segment[]): Promise<void[]>
+    {
+        const promises = segments.map(async (segment) => this.#buildSegmentModuleCache(segment));
+
+        return Promise.all(promises);
+    }
+
+    async #buildSegmentModuleCache(segment: Segment): Promise<void>
+    {
+        await this.#buildSegmentCacheForRepository(segment);
+        await this.#buildSegmentCacheForNode(segment);
+    }
+
+    async #buildSegmentCacheForRepository(segment: Segment): Promise<void>
+    {
+        return this.#buildSegmentDefinitionForRepository(segment);
+    }
+
+    async #buildSegmentDefinitionForRepository(segment: Segment): Promise<void>
+    {
+        // For the repository we need to make a definition file that contains all segment filenames
+        // used for building a lookup table (mapping source files to segments).
+
+        const code = this.#createSegmentRepositoryCode(segment);
+        const filename = this.#createSegmentRepositoryFilename(segment);
+
+        return this.#cacheManager.store(filename, code);
+    }
+
+    #createSegmentRepositoryCode(segment: Segment): string
+    {
+        const filenames = segment.getFilenames();
+        const relativeLocations = filenames.map(filename => this.#sourceManager.getRelativeLocation(filename));
+
+        return `export const files = [\n\t"${[...relativeLocations].join('",\n\t"')}"\n];`;
+    }
+
+    #createSegmentRepositoryFilename(segment: Segment): string
+    {
+        const filename = this.#extractSegmentFilename(segment);
+
+        return filename.replace('.json', '.repository.js');
+    }
+
+    async #buildSegmentCacheForNode(segment: Segment): Promise<void>
+    {
+        await this.#buildSegmentDefinitionForNode(segment);
+        await this.#buildSegmentModulesForNode(segment);
+    }
+
+    async #buildSegmentDefinitionForNode(segment: Segment): Promise<void>
+    {
+        // For the node we need to make a definition file that imports all segment procedures
+        // and exports them as a segment model containing the procedures with the meta-data.
+
+        const code = this.#createSegmentNodeCode(segment);
+        const filename = this.#createSegmentNodeFilename(segment);
+
+        return this.#cacheManager.store(filename, code);
+    }
+
+    #createSegmentNodeCode(segment: Segment): string
+    {
+        const importCode = this.#createSegmentImportCode(segment);
+        const modelCode = this.#createSegmentModelCode(segment);
+
+        return `${importCode}\n\n${modelCode}`;
+    }
+
+    #createSegmentImportCode(segment: Segment): string
+    {
+        let codes: string[] = [];
+
+        for (const module of segment.modules)
+        {
+            const relativeLocation = this.#sourceManager.getRelativeLocation(module.filename);
+            const imports: string[] = [];
+
+            for (const [importKey, implementation] of module.implementations)
+            {
+                imports.push(`${importKey} as \$${implementation.id}`);
+            }
+
+            codes.push(`import { ${imports.join(',')} } from "./${relativeLocation}";`);
+        }
+
+        return codes.join('\n');
+    }
+
+    #createSegmentModelCode(segment: Segment): string
+    {
+        const procedureCode: string[] = [];
+
+        for (const procedure of segment.procedures.values())
+        {
+            const implementationCode: string[] = [];
+
+            for (const implementation of procedure.implementations)
+            {
+                implementationCode.push(`{ access: "${implementation.access}", version: "${implementation.version}", executable: \$${implementation.id} }`);
+            }
+
+            procedureCode.push(`{ module: "${procedure.module}", name: "${procedure.name}", implementations: [\n\t\t${implementationCode.join(',\n\t\t')}\n\t]}`);
+        }
+
+        return `export const procedures = [\n\t${procedureCode.join(',\n\t')}\n];`;
+    }
+
+    async #buildSegmentModulesForNode(segment: Segment): Promise<void>
+    {
+        // For the node we need to create two new module files:
+        // 1) A copy of the original module file with distribution safe imports.
+        // 2) A remake of the original module file with remote implementations only.
+
+        for (const module of segment.modules)
+        {
+            const filename = module.filename;
+
+            const absoluteLocation = this.#sourceManager.getAbsoluteLocation(filename);
+            const relativeLocation = this.#sourceManager.getRelativeLocation(filename);
+
+            const file = await this.#sourceManager.load(absoluteLocation);
+            const code = file.content.toString();
+
+            await this.#buildSegmentModuleForLocal(code, relativeLocation);
+            await this.#buildSegmentModuleForRemote(module, relativeLocation);
+        }
+    }
+
+    async #buildSegmentModuleForLocal(code: string, location: string): Promise<void>
+    {
+        const importedCode = ImportRewriter.rewrite(code);
+        const nodeLocation = location.replace('.js', '.local.js');
+
+        return this.#cacheManager.store(nodeLocation, importedCode);
+    }
+
+    async #buildSegmentModuleForRemote(module: SegmentModule, location: string): Promise<void>
+    {
+        const remoteCode = RemoteBuilder.build(module);
+        const remoteLocation = location.replace('.js', '.remote.js');
+
+        return this.#cacheManager.store(remoteLocation, remoteCode);
+    }
+
+    #createSegmentNodeFilename(segment: Segment): string
+    {
+        const filename = this.#extractSegmentFilename(segment);
+
+        return filename.replace('.json', '.local.js');
+    }
+
+    #extractSegmentFilename(segment: Segment): string
+    {
+        const filename = segment.filename.split('/').pop();
+
+        if (filename === undefined)
+        {
+            throw new InvalidSegmentFilename(segment.filename);
+        }
+
+        return filename;
+    }
+
+    async #buildApplicationCache(applicationModules: ApplicationModule[]): Promise<void[]>
+    {
+        const promises = applicationModules.map(async (module) => this.#buildApplicationModuleCache(module));
+
+        return Promise.all(promises);
+    }
+
+    async #buildApplicationModuleCache(module: ApplicationModule): Promise<void>
+    {
+        return this.#buildApplicationShareables(module);
+    }
+
+    async #buildApplicationShareables(module: ApplicationModule): Promise<void>
+    {
+        // Applications use class objects as shareables to share data between segments.
+        // In order to make make this work we need to append their source (file) to the
+        // class definition so that they can be (de)serialized.
+
+        if (module.hasClasses() === false)
+        {
+            return;
+        }
+
+        const filename = module.filename;
+        const file = await this.#sourceManager.load(filename);
+        const code = file.content.toString();
+
+        const sourcedCode = SourceAppender.append(module, code, filename);
+
+        return this.#cacheManager.store(filename, sourcedCode);
+    }
+}

package/src/runtime/caching/ImportRewriter.ts

@@ -0,0 +1,76 @@
+
+import * as Keywords from './definitions/Keywords.js';
+
+const IMPORT_PATTERN = /import(?:["'\s]*([\w*{}\n, ]+)from\s*)?["'\s]*([@\w/_-]+)["'\s].*/g;
+const NON_SYSTEM_INDICATORS = ['.', '/', 'http:', 'https:'];
+
+class Dependency
+{
+    items: string;
+    from: string;
+
+    constructor(items: string, from: string)
+    {
+        this.items = items;
+        this.from = from;
+    }
+}
+
+export default class ImportRewriter
+{
+    static rewrite(content: string): string
+    {
+        const replacer = (statement: string) => this.#replaceImport(statement);
+        const newContent = content.replaceAll(IMPORT_PATTERN, replacer);
+
+        return newContent !== content
+            ? this.#insertGetDependency(newContent)
+            : newContent;
+    }
+
+    static #replaceImport(statement: string): string
+    {
+        const dependency = this.#parseImport(statement);
+
+        return this.#isSystemDependency(dependency)
+            ? this.#rewriteImport(dependency)
+            : statement;
+    }
+
+    static #parseImport(statement: string): Dependency
+    {
+        const hasSemicolon = statement.endsWith(';');
+        const fromIndex = statement.indexOf('from');
+        const endIndex = statement.length - (hasSemicolon ? 1 : 0);
+
+        const items = statement.substring(6, fromIndex).trim();
+        const from = statement.substring(fromIndex + 4, endIndex).trim().slice(1, -1);
+
+        return new Dependency(items, from);
+    }
+
+    static #isSystemDependency(dependency: Dependency): boolean
+    {
+        return NON_SYSTEM_INDICATORS.some(indicator => dependency.from.startsWith(indicator)) === false;
+    }
+
+    static #isJitarDependency(dependency: Dependency): boolean
+    {
+        return dependency.from === Keywords.JITAR;
+    }
+
+    static #rewriteImport(dependency: Dependency): string
+    {
+        if (this.#isJitarDependency(dependency))
+        {
+            return `import ${dependency.items} from "/jitar/hooks.js";`;
+        }
+
+        return `const ${dependency.items} = await getDependency('${dependency.from}');`;
+    }
+
+    static #insertGetDependency(module: string): string
+    {
+        return `import { getDependency } from "/jitar/hooks.js";\n${module}`;
+    }
+}

package/src/runtime/caching/RemoteBuilder.ts

@@ -0,0 +1,51 @@
+
+import * as AccessLevel from '../../core/definitions/AccessLevel.js';
+import ReflectionHelper from '../../core/reflection/ReflectionHelper.js';
+
+import Implementation from './models/Implementation.js';
+import SegmentModule from './models/SegmentModule.js';
+import * as Keywords from './definitions/Keywords.js';
+
+export default class RemoteBuilder
+{
+    static build(module: SegmentModule): string
+    {
+        let code = this.#createRemoteImports();
+
+        for (const [importKey, implementation] of module.implementations)
+        {
+            if (implementation.access !== AccessLevel.PUBLIC)
+            {
+                continue;
+            }
+
+            const asDefault = importKey === Keywords.DEFAULT;
+
+            code += this.#createRemoteCode(implementation, asDefault);
+        }
+
+        return code;
+    }
+
+    static #createRemoteImports(): string
+    {
+        return `import { runProcedure } from "/jitar/hooks.js";\n`;
+    }
+
+    static #createRemoteCode(implementation: Implementation, asDefault: boolean): string
+    {
+        const parameters = ReflectionHelper.getFunctionParameters(implementation.executable as Function);
+        const parameterNames = parameters.map(parameter => parameter.name);
+
+        const procedureName = implementation.executable.name;
+        const procedureFqn = implementation.fqn;
+        const procedureVersion = implementation.version;
+        const procedueParameters = parameterNames.join(', ');
+        const procedureArguments = parameterNames.map(name => `'${name}': ${name}`).join(', ');
+
+        const functionName = `\nexport ${asDefault ? `${Keywords.DEFAULT} ` : ''}async function ${procedureName}(${procedueParameters})`;
+        const functionBody = `return runProcedure('${procedureFqn}', '${procedureVersion}', { ${procedureArguments} })`;
+
+        return `${functionName} {\n\t${functionBody}\n}\n`;
+    }
+}

package/src/runtime/caching/SourceAppender.ts

@@ -0,0 +1,57 @@
+
+import ApplicationModule from './models/ApplicationModule.js';
+import * as Keywords from './definitions/Keywords.js';
+
+export default class SourceAppender
+{
+    static append(module: ApplicationModule, code: string, filename: string): string
+    {
+        const classNames = this.#extractClassNames(module);
+
+        if (classNames.length === 0)
+        {
+            return code;
+        }
+
+        const sourceCode = this.#createSourceCode(filename, classNames);
+
+        return `${code}\n${sourceCode}`;
+    }
+
+    static #extractClassNames(module: ApplicationModule): string[]
+    {
+        const classes = module.classes;
+        const names: string[] = [];
+
+        for (const key of classes.keys())
+        {
+            const clazz = classes.get(key) as Function;
+
+            if (clazz.name === '')
+            {
+                // The  exported object does not have a name,
+                // so we can't add the source properties.
+                continue;
+            }
+
+            if (key !== Keywords.DEFAULT && key !== clazz.name)
+            {
+                // The object is being (re) exported under another name.
+                // We need to skip this because we can't be sure the real
+                // object is present in the module.
+                continue;
+            }
+
+            names.push(clazz.name);
+        }
+
+        return names;
+    }
+
+    static #createSourceCode(filename: string, classNames: string[]): string
+    {
+        const codes = classNames.map(className => `${className}.source = '${filename}';`);
+
+        return codes.join('\n');
+    }
+}

package/src/runtime/caching/definitions/Keywords.ts

@@ -0,0 +1,3 @@
+
+export const DEFAULT = 'default';
+export const JITAR = 'jitar';

package/src/runtime/caching/errors/InvalidSegmentFilename.ts

@@ -0,0 +1,8 @@
+
+export default class InvalidSegmentFilename extends Error
+{
+    constructor(filename: string)
+    {
+        super(`Segment filename '${filename}' is invalid`);
+    }
+}

package/src/runtime/caching/errors/MissingModuleExport.ts

@@ -0,0 +1,8 @@
+
+export default class MissingModuleExport extends Error
+{
+    constructor(filename: string, key: string)
+    {
+        super(`Module '${filename}' does not export '${key}'`);
+    }
+}

package/src/runtime/caching/errors/SegmentFileNotLoaded.ts

@@ -0,0 +1,8 @@
+
+export default class SegmentFileNotLoaded extends Error
+{
+    constructor(filename: string)
+    {
+        super(`Failed to load segment file '${filename}'`);
+    }
+}

package/src/runtime/caching/errors/SegmentModuleNotLoaded.ts

@@ -0,0 +1,8 @@
+
+export default class SegmentModuleNotLoaded extends Error
+{
+    constructor(filename: string)
+    {
+        super(`Segment module could not be loaded from '${filename}'`);
+    }
+}