@luna-park/plugin 1.7.0 → 2.0.0

package/README.md

@@ -1,139 +1,229 @@
-# @luna-park/plugin
-
-This package provides the core types and helper functions for creating plugins for **Luna Park**, a visual scripting platform.
-
-It exports the necessary interfaces to define plugin configurations, editor components, logic nodes, and lifecycle hooks.
-
-## Installation
-
-```bash
-npm install @luna-park/plugin
-```
-
-## Usage
-
-The primary way to define a plugin is using the `makePlugin` helper function. This ensures type safety for your plugin configuration.
-
-```typescript
-import { makePlugin, ELogicType } from "@luna-park/plugin";
-import awesomeIcon from "./awesome-icon.svg"; // Icon URL
-
-export default makePlugin({
-    id: "my-awesome-plugin",
-    name: "My Awesome Plugin",
-    icon: awesomeIcon, // Icon URL
-    description: "Adds amazing capabilities to Luna Park.",
-
-    // Plugin configuration schema (optional)
-    config: LogicType.object({
-        apiKey: LogicType.string(),
-        theme: LogicType.string({enum: ["light", "dark"], default: "dark"}),
-    }),
-
-    // Lifecycle hooks (optional)
-    lifecycle: {
-        mount: async (env) => {
-            console.log("Plugin mounted", env.config.apiKey);
-        },
-        update: async ({config}) => {
-            console.log("Config updated", config);
-        },
-        unmount: (env) => {
-            console.log("Plugin unmounted");
-        },
-    },
-
-    // Extend the editor
-    editor: {
-        // Register custom Vue components for the editor (optional)
-        components: [
-            {
-                name: "Element/Avatar",
-                component: MyAvatarComponent,
-                properties: {
-                    src: LogicType.string({ name: "Avatar URL" }),
-                    name: LogicType.string({ name: "Name" }),
-                },
-                slots: {
-                    default: LogicType.void()
-                }
-            }
-            // ... component definitions
-        ],
-        
-        // Register custom logic nodes (optional)
-        nodes: [
-            makeLogicNode({
-                name: "log/stuff",
-                inputs: {
-                    in_exec: LogicType.exec(),
-                    in_stuff: LogicType.string({ name: "Stuff" })
-                },
-                outputs: {
-                    out_exec: LogicType.exec()
-                },
-                methods: {
-                    async in_exec() {
-                        console.log(this.in_stuff);
-                        await this.out_exec();
-                    }
-                },
-                display: {
-                    name: "Log stuff"
-                }
-            })
-            // ... node definitions
-        ],
-        
-        // Register wrapper for the editor (optional)
-        wrapper : MyWrapperComponent,
-    },
-    
-    // Code injection options (optional)
-    inject: {
-        css: "body { background-color: #000; }",
-        js: "console.log('Hello world!')"
-    }
-});
-```
-
-## API Reference
-
-### `makePlugin(plugin)`
-
-A helper identity function that takes a `TPlugin` object and returns it. It is used to infer types for the configuration and internal state.
-
-### `TPlugin<TConfig, TInternal>`
-
-The main interface for defining a plugin.
-
-| Property | Type | Description |
-| :--- | :--- | :--- |
-| `id` | `string` | **Required**. Unique identifier for the plugin. |
-| `name` | `string` | **Required**. Display name of the plugin. |
-| `icon` | `string` | **Required**. Icon for the plugin. |
-| `description` | `string` | Brief description of what the plugin does. |
-| `config` | `TSchema` | Schema definition for the plugin's configuration settings. |
-| `lifecycle` | `object` | Lifecycle hooks (`mount`, `unmount`, `update`). |
-| `editor` | `object` | Extensions for the editor (components, nodes, tokens, wrapper). |
-| `build` | `object` | Build-time configurations (Vite plugins, imports). |
-| `inject` | `object` | CSS/JS injection options. |
-
-### `TEnv<TConfig, TInternal>`
-
-The environment object passed to lifecycle hooks and dynamic options.
-
-| Property    | Type                  | Description |
-|:------------|:----------------------| :--- |
-| `app`       | `TApplication`  | Access to the core application instance. |
-| `config`    | `Static<TConfig>`     | The resolved configuration values based on the schema. |
-| `mode`      | `"build" \| "editor"` | The current running mode. |
-| `internals` | `TInternals`          | Internal state (if defined). |
-
-### `TOption<TEnv, T>`
-
-Many properties in `TPlugin` can be either a static value `T` or a function that returns `T` (or `Promise<T>`). This allows for dynamic configuration based on the environment.
-
-```typescript
-type TOption<TEnv, T> = T | ((env: TEnv) => T | Promise<T>);
-```
+# @luna-park/plugin
+
+This package provides the core types and helper functions for creating plugins for **Luna Park**, a visual scripting platform.
+
+It exports the necessary interfaces to define plugin configurations, editor components, logic nodes, and lifecycle hooks.
+
+## Installation
+
+```bash
+npm install @luna-park/plugin
+```
+
+## Usage
+
+The primary way to define a plugin is using the `makePlugin` helper function. This ensures type safety for your plugin configuration.
+
+```typescript
+import { makePlugin, ELogicType } from "@luna-park/plugin";
+import awesomeIcon from "./awesome-icon.svg"; // Icon URL
+
+export default makePlugin({
+    id: "my-awesome-plugin",
+    name: "My Awesome Plugin",
+    icon: awesomeIcon, // Icon URL
+    description: "Adds amazing capabilities to Luna Park.",
+
+    // Plugin configuration schema (optional)
+    config: LogicType.object({
+        apiKey: LogicType.string(),
+        theme: LogicType.string({enum: ["light", "dark"], default: "dark"}),
+    }),
+
+    // Lifecycle hooks (optional)
+    lifecycle: {
+        mount: async (env) => {
+            console.log("Plugin mounted", env.config.apiKey);
+        },
+        update: async ({config}) => {
+            console.log("Config updated", config);
+        },
+        unmount: (env) => {
+            console.log("Plugin unmounted");
+        },
+    },
+
+    // Extend the editor
+    editor: {
+        // Register custom Vue components for the editor (optional)
+        components: [
+            {
+                name: "Element/Avatar",
+                component: MyAvatarComponent,
+                properties: {
+                    src: LogicType.string({ name: "Avatar URL" }),
+                    name: LogicType.string({ name: "Name" }),
+                },
+                slots: {
+                    default: LogicType.void()
+                }
+            }
+            // ... component definitions
+        ],
+        
+        // Register custom logic nodes (optional)
+        nodes: [
+            makeLogicNode({
+                name: "log/stuff",
+                inputs: {
+                    in_exec: LogicType.exec(),
+                    in_stuff: LogicType.string({ name: "Stuff" })
+                },
+                outputs: {
+                    out_exec: LogicType.exec()
+                },
+                methods: {
+                    async in_exec() {
+                        console.log(this.in_stuff);
+                        await this.out_exec();
+                    }
+                },
+                display: {
+                    name: "Log stuff"
+                }
+            })
+            // ... node definitions
+        ],
+        
+        // Register wrapper for the editor (optional)
+        wrapper : MyWrapperComponent,
+    },
+    
+    // Code injection options (optional)
+    inject: {
+        css: "body { background-color: #000; }",
+        js: "console.log('Hello world!')"
+    }
+});
+```
+
+## API Reference
+
+### `makePlugin(plugin)`
+
+A helper identity function that takes a `TPlugin` object and returns it. It is used to infer types for the configuration and internal state.
+
+### `TPlugin<TConfig, TInternal>`
+
+The main interface for defining a plugin.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | **Required**. Unique identifier for the plugin. |
+| `name` | `string` | **Required**. Display name of the plugin. |
+| `icon` | `string` | **Required**. Icon for the plugin. |
+| `description` | `string` | Brief description of what the plugin does. |
+| `api` | `TOption<TEnv, unknown>` | Functions exposed to other plugins (see below). |
+| `config` | `TSchema` | Schema definition for the plugin's configuration settings. |
+| `dependencies` | `Array<{ id, name, target }>` | Other plugins this plugin requires (see below). |
+| `lifecycle` | `object` | Lifecycle hooks (`mount`, `unmount`, `update`). |
+| `editor` | `object` | Extensions for the editor (components, nodes, tokens, wrapper). |
+| `build` | `object` | Build-time configurations (Vite plugins, imports). |
+| `inject` | `object` | CSS/JS injection options. |
+
+### Dependencies
+
+A plugin can depend on other plugins. Missing dependencies are installed alongside it, and dependencies are always loaded, mounted and injected before the plugins that require them.
+
+```typescript
+export default makePlugin({
+    id: "my-awesome-plugin",
+    // ...
+    dependencies: [
+        { id: "nuxt-ui", name: "Nuxt UI", target: "@luna-park/plugin-nuxt-ui" }
+    ]
+});
+```
+
+| Property | Description |
+| :--- | :--- |
+| `id` | The `id` of the required plugin. |
+| `name` | Display name, shown before the dependency is installed. |
+| `target` | npm package name or URL used to install it. |
+
+`sortPlugins(plugins)` returns the given plugins in dependency order.
+
+### Using another plugin's functions
+
+A plugin exposes functions through `api`, built from its own environment (its config and internals). Other plugins get it with `env.getPlugin(id)`. Import only the API type from the dependency so its code is not bundled twice.
+
+```typescript
+// @luna-park/plugin-a
+export type TPluginAApi = { greet: (name: string) => string; };
+
+export default makePlugin({
+    id: "plugin-a",
+    // ...
+    api: (env): TPluginAApi => ({
+        greet: (name) => `${ env.config.greeting } ${ name }`
+    })
+});
+
+// @luna-park/plugin-b
+import type { TPluginAApi } from "@luna-park/plugin-a";
+
+export default makePlugin({
+    id: "plugin-b",
+    // ...
+    dependencies: [{ id: "plugin-a", name: "Plugin A", target: "@luna-park/plugin-a" }],
+    lifecycle: {
+        mount: async (env) => {
+            const pluginA = await env.getPlugin<TPluginAApi>("plugin-a");
+            env.log(pluginA?.greet("world") ?? "Plugin A is not installed");
+        }
+    }
+});
+```
+
+`getPlugin` resolves to `undefined` when the plugin is not installed or exposes no `api`. It works in both `editor` and `build` modes, and dependencies are always loaded first.
+
+### `TEnv<TConfig, TInternal>`
+
+The environment object passed to lifecycle hooks and dynamic options.
+
+| Property    | Type                  | Description |
+|:------------|:----------------------| :--- |
+| `app`       | `TApplication`  | Access to the core application instance. |
+| `config`    | `Static<TConfig>`     | The resolved configuration values based on the schema. |
+| `backend`   | `object`              | Editor backend helpers (see below). |
+| `getPlugin` | `(id) => Promise<TApi>` | Get the `api` of another installed plugin. |
+| `host`      | `THost \| undefined`  | Desktop app helpers (see below). Editor only. |
+| `mode`      | `"build" \| "editor"` | The current running mode. |
+| `internals` | `TInternals`          | Internal state (if defined). |
+
+#### Transactions
+
+Backend logic can run inside a database transaction (the `DB Transaction` node, or the editor's test runs, which are always rolled back). When a plugin changes something outside the database, it follows the transaction with:
+
+| Function | Description |
+| :--- | :--- |
+| `backend.onCommit(callback)` | Runs `callback` once the current transaction is committed, or right away outside a transaction. |
+| `backend.onRollback(callback)` | Runs `callback` if the current transaction is rolled back. Ignored outside a transaction. |
+
+```typescript
+await saveContent(id, content);
+env.backend.onRollback(() => deleteContent(id));
+```
+
+The generated backend exposes the same functions as `onCommit` and `onRollback` from `@/database/index.js`.
+
+#### Desktop host
+
+In the desktop app, `host.available` is `true` and the plugin can use:
+
+| Function | Description |
+| :--- | :--- |
+| `host.readFile(path)` | Reads a file of the project folder (`undefined` if it doesn't exist). |
+| `host.writeFile(path, data)` | Writes a file of the project folder, creating its folders. |
+| `host.removeFile(path)` | Removes a file of the project folder. |
+| `host.fetch(input, init)` | `fetch` without CORS restrictions. |
+
+Paths are relative to the project folder and can't leave it. In the web editor, `host` is `undefined` or `host.available` is `false`.
+
+### `TOption<TEnv, T>`
+
+Many properties in `TPlugin` can be either a static value `T` or a function that returns `T` (or `Promise<T>`). This allows for dynamic configuration based on the environment.
+
+```typescript
+type TOption<TEnv, T> = T | ((env: TEnv) => T | Promise<T>);
+```