feat: introduce module system

api/src/main/java/org/densy/scriptify/api/exception/ScriptModuleCopyException.java

@@ -0,0 +1,35 @@
+package org.densy.scriptify.api.exception;
+
+/**
+ * Custom exception for errors while script copy process.
+ */
+public class ScriptModuleCopyException extends RuntimeException {
+
+    /**
+     * Creates a new ScriptModuleCopyException with the specified message.
+     *
+     * @param message the detail message
+     */
+    public ScriptModuleCopyException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new ScriptModuleCopyException with the specified message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
+    public ScriptModuleCopyException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Creates a new ScriptModuleCopyException with the specified cause.
+     *
+     * @param cause the cause of the exception
+     */
+    public ScriptModuleCopyException(Throwable cause) {
+        super(cause);
+    }
+}

api/src/main/java/org/densy/scriptify/api/exception/ScriptModuleLoadException.java

@@ -0,0 +1,35 @@
+package org.densy.scriptify.api.exception;
+
+/**
+ * Custom exception for errors while script load process.
+ */
+public class ScriptModuleLoadException extends ScriptException {
+
+    /**
+     * Creates a new ScriptModuleLoadException with the specified message.
+     *
+     * @param message the detail message
+     */
+    public ScriptModuleLoadException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new ScriptModuleLoadException with the specified message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
+    public ScriptModuleLoadException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Creates a new ScriptModuleLoadException with the specified cause.
+     *
+     * @param cause the cause of the exception
+     */
+    public ScriptModuleLoadException(Throwable cause) {
+        super(cause);
+    }
+}

api/src/main/java/org/densy/scriptify/api/exception/ScriptModuleWrongContextException.java

@@ -0,0 +1,17 @@
+package org.densy.scriptify.api.exception;
+
+/**
+ * Custom exception for errors when script module context mismatch occurs.
+ */
+public class ScriptModuleWrongContextException extends ScriptException {
+
+    /**
+     * Creates a new ScriptModuleWrongContextException  with the specified message.
+     *
+     * @param expected the expected context
+     * @param actual the given context
+     */
+    public ScriptModuleWrongContextException(Class<?> expected, Class<?> actual) {
+        super("Expected context of type " + expected.getName() + " but got " + actual.getName());
+    }
+}

api/src/main/java/org/densy/scriptify/api/script/Script.java

@@ -4,6 +4,7 @@
 import org.densy.scriptify.api.exception.ScriptFunctionException;
 import org.densy.scriptify.api.script.constant.ScriptConstantManager;
 import org.densy.scriptify.api.script.function.ScriptFunctionManager;
+import org.densy.scriptify.api.script.module.ScriptModuleManager;
 import org.densy.scriptify.api.script.security.ScriptSecurityManager;
 
 /**
@@ -21,6 +22,8 @@ public interface Script<T> {
      */
     ScriptSecurityManager getSecurityManager();
 
+    ScriptModuleManager getModuleManager();
+
     /**
      * Retrieves the function manager associated with this script.
      *

api/src/main/java/org/densy/scriptify/api/script/module/ScriptExternalModule.java

@@ -0,0 +1,19 @@
+package org.densy.scriptify.api.script.module;
+
+import org.densy.scriptify.api.exception.ScriptModuleLoadException;
+
+/**
+ * A script module loaded from an external source.
+ */
+public interface ScriptExternalModule extends ScriptModule {
+
+    /**
+     * Loads the module source as bytes.
+     */
+    byte[] load() throws ScriptModuleLoadException;
+
+    /**
+     * Gets external module source name.
+     */
+    String getSourceName();
+}

api/src/main/java/org/densy/scriptify/api/script/module/ScriptFileExternalModule.java

@@ -0,0 +1,19 @@
+package org.densy.scriptify.api.script.module;
+
+import java.nio.file.Path;
+
+/**
+ * An external module backed by a file or directory on disk.
+ * <p>
+ * If path points to a directory, entry point is resolved automatically.
+ */
+public interface ScriptFileExternalModule extends ScriptExternalModule {
+    Path getPath();
+
+    /**
+     * Gets entry point filename when path is a directory.
+     * */
+    default String getEntryPoint() {
+        return "index.mjs";
+    }
+}

api/src/main/java/org/densy/scriptify/api/script/module/ScriptInternalModule.java

@@ -0,0 +1,34 @@
+package org.densy.scriptify.api.script.module;
+
+import org.densy.scriptify.api.script.module.export.ScriptExport;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.UnmodifiableView;
+
+import java.util.Collection;
+
+/**
+ * A module that exports elements to the script environment. Modules can be accessed via ES import (in JavaScript).
+ */
+public interface ScriptInternalModule extends ScriptModule {
+
+    /**
+     * Gets collection of all exports in module.
+     *
+     * @return Collection with ScriptExport
+     */
+    @UnmodifiableView Collection<ScriptExport> getExports();
+
+    /**
+     * Adds export to the module.
+     *
+     * @param export export to add
+     */
+    void export(ScriptExport export);
+
+    /**
+     * Copies all exports from the target module that are not present in the current module.
+     *
+     * @param module target module
+     */
+    void copy(ScriptInternalModule module);
+}

api/src/main/java/org/densy/scriptify/api/script/module/ScriptModule.java

@@ -0,0 +1,14 @@
+package org.densy.scriptify.api.script.module;
+
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A base interface for all module types.
+ */
+public interface ScriptModule {
+
+    /**
+     * Gets module name. For ES import "@densy/mymodule".
+     */
+    @NotNull String getName();
+}

api/src/main/java/org/densy/scriptify/api/script/module/ScriptModuleManager.java

@@ -0,0 +1,63 @@
+package org.densy.scriptify.api.script.module;
+
+import org.densy.scriptify.api.script.module.export.resolver.ScriptModuleExportResolverFactory;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.UnmodifiableView;
+
+import java.util.Map;
+
+/**
+ * Manages all modules available to the script.
+ */
+public interface ScriptModuleManager {
+
+    /**
+     * Gets a factory for module export values.
+     *
+     * @return ScriptModuleExportResolverFactory
+     */
+    ScriptModuleExportResolverFactory getModuleExportResolver();
+
+    /**
+     * Sets a custom factory for module export values.
+     *
+     * @param factory ScriptModuleExportResolverFactory to set
+     */
+    void setModuleExportResolver(ScriptModuleExportResolverFactory factory);
+
+    /**
+     * Gets the internal global module. Exports added here are available globally without import.
+     */
+    ScriptInternalModule getGlobalModule();
+
+    /**
+     * Gets all registered modules.
+     *
+     * @return Map<String, ScriptModule>
+     */
+    @UnmodifiableView Map<String, ScriptModule> getModules();
+
+    /**
+     * Gets registered module by name.
+     *
+     * @param name the module name
+     * @return found module or null
+     */
+    default @Nullable ScriptModule getModule(String name) {
+        return this.getModules().get(name);
+    }
+
+    /**
+     * Adds module to the script.
+     *
+     * @param module module to add
+     */
+    void addModule(ScriptModule module);
+
+    /**
+     * Removes registered module from the script.
+     *
+     * @param name the name of module to remove
+     */
+    void removeModule(String name);
+}

api/src/main/java/org/densy/scriptify/api/script/module/ScriptStreamExternalModule.java

@@ -0,0 +1,8 @@
+package org.densy.scriptify.api.script.module;
+
+/**
+ * An external module loaded from an arbitrary byte source.
+ */
+public interface ScriptStreamExternalModule extends ScriptExternalModule {
+    // do nothing here
+}

api/src/main/java/org/densy/scriptify/api/script/module/export/ScriptExport.java

@@ -0,0 +1,8 @@
+package org.densy.scriptify.api.script.module.export;
+
+/**
+ * Represents any exportable element from a module.
+ */
+public interface ScriptExport {
+    String getName();
+}

api/src/main/java/org/densy/scriptify/api/script/module/export/ScriptValueExport.java

@@ -0,0 +1,33 @@
+package org.densy.scriptify.api.script.module.export;
+
+import lombok.Getter;
+
+/**
+ * Universal wrapper for exporting Java values and classes.
+ *
+ * <pre>
+ *   new ScriptValueExport("PI", 3.14)               - PI available as a number
+ *   new ScriptValueExport("MyClass", MyClass.class) - new MyClass() in JS
+ *   new ScriptValueExport("service", myService)     - access to instance methods
+ * </pre>
+ */
+@Getter
+public class ScriptValueExport implements ScriptExport {
+
+    private final String name;
+    private final Object value;
+
+    public ScriptValueExport(String name, Object value) {
+        this.name = name;
+        this.value = value;
+    }
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    public boolean isClass() {
+        return value instanceof Class<?>;
+    }
+}

api/src/main/java/org/densy/scriptify/api/script/module/export/resolver/ScriptModuleExportResolver.java

@@ -0,0 +1,17 @@
+package org.densy.scriptify.api.script.module.export.resolver;
+
+import org.densy.scriptify.api.script.module.export.ScriptExport;
+
+/**
+ * A value resolver for export. Used to determine which value in the script will be exported.
+ */
+public interface ScriptModuleExportResolver {
+
+    /**
+     * Resolves the value of export.
+     *
+     * @param export target export
+     * @return resolved value
+     */
+    Object resolve(ScriptExport export);
+}

api/src/main/java/org/densy/scriptify/api/script/module/export/resolver/ScriptModuleExportResolverFactory.java

@@ -0,0 +1,18 @@
+package org.densy.scriptify.api.script.module.export.resolver;
+
+import org.densy.scriptify.api.exception.ScriptModuleWrongContextException;
+
+/**
+ * A factory for creating an export resolver.
+ */
+public interface ScriptModuleExportResolverFactory {
+
+    /**
+     * Creates a resolver.
+     *
+     * @param context Engine context. Depends on the specific implementation.
+     * @return created ScriptModuleExportResolver
+     * @throws ScriptModuleWrongContextException if an incorrect context is passed to a specific implementation of the engine.
+     */
+    ScriptModuleExportResolver create(Object context) throws ScriptModuleWrongContextException;
+}

build.gradle.kts

@@ -12,7 +12,7 @@ java {
 
 allprojects {
     group = "org.densy.scriptify"
-    version = "1.5.0-SNAPSHOT"
+    version = "1.6.0-SNAPSHOT"
 }
 
 subprojects {

common/src/main/java/org/densy/scriptify/common/script/constant/CommonConstantManager.java

@@ -4,6 +4,10 @@
 import org.densy.scriptify.core.script.constant.impl.ScriptConstantBaseDir;
 import org.densy.scriptify.core.script.constant.impl.ScriptConstantOsName;
 
+/**
+ * @deprecated this class is marked as deprecated in version 1.6. Modules have replaced managers.
+ */
+@Deprecated(forRemoval = true)
 public class CommonConstantManager extends StandardConstantManager {
 
     public CommonConstantManager() {

common/src/main/java/org/densy/scriptify/common/script/function/CommonFunctionManager.java

@@ -16,6 +16,10 @@
 import org.densy.scriptify.common.script.function.impl.zip.ScriptFunctionZipFile;
 import org.densy.scriptify.core.script.function.StandardFunctionManager;
 
+/**
+ * @deprecated this class is marked as deprecated in version 1.6. Modules have replaced managers.
+ */
+@Deprecated(forRemoval = true)
 public class CommonFunctionManager extends StandardFunctionManager {
 
     public CommonFunctionManager() {