npm - @codenotch/codenotch.react - Versions diffs - 2.0.0 → 2.0.2 - Mend

@codenotch/codenotch.react 2.0.0 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/dist/index.d.ts +2 -29
package/dist/index.d.ts.map +1 -1
package/dist/index.js +88 -112
package/dist/models/Codenotch.d.ts +8 -129
package/dist/models/Codenotch.d.ts.map +1 -1
package/package.json +3 -4
package/src/index.ts +93 -128
package/src/models/Codenotch.ts +8 -146
package/README.md +0 -183
package/src/core/ProcessUtils.ts +0 -86
package/src/core/SignalR.ts +0 -375

package/README.md DELETED Viewed

@@ -1,183 +0,0 @@
-# codenotch-react
-React bindings for [Codenotch](https://codenotch.com) applications.
-Codenotch is a full-stack development platform: a project combines server-side **BPMN processes**, **SQL tables** / **NoSQL documents**, **i18n** translations and **React** apps. This package is the client-side bridge between those React apps and the Codenotch runtime: it lets a component start BPMN processes, run CNQL queries, translate i18n keys, listen to real-time signals, and manage theme/language.
-> **Requirements** — Codenotch apps run on **React 19** (`react@^19`, `react-dom@^19`). The package uses the automatic JSX runtime and `createRoot`; all modern React APIs (hooks, `useId`, `use`, Actions…) are available.
-## Quick start
-```tsx
-import { useCodenotch } from 'codenotch-react';
-const MyApp = () => {
-    const cn = useCodenotch();
-    return <div className="p-4">
-        <h1 className="text-xl font-bold">{cn.i18n('welcome')}</h1>
-    </div>;
-};
-export default MyApp;
-```
-`useCodenotch()` is a real React hook: the returned object is stable across renders and is replaced — re-rendering the component — whenever the environment changes (`setLanguage`, `setTheme`, `init`). Regular hook rules apply. The same API is available everywhere else through two non-hook entry points:
-| Where | Use |
-|-------|-----|
-| Function component / custom hook | `const cn = useCodenotch();` — re-renders on language/theme change. |
-| Class component | `export default withCodenotch(MyClass);` — injects `this.props.cn`, re-renders on change, forwards `ref`. |
-| Event handler, plain module, service, anywhere | `getCodenotch()` — plain function, never stale, no re-render. |
-| Manual subscription (rare) | `onCodenotchChange(listener)` → `IDisposable`. |
-```tsx
-import React from 'react';
-import { withCodenotch, WithCodenotchProps } from 'codenotch-react';
-interface Props extends WithCodenotchProps {
-    userId: string;
-}
-class TodoList extends React.Component<Props> {
-    render() {
-        return <h1>{this.props.cn.i18n('todos.title')}</h1>;
-    }
-}
-export default withCodenotch(TodoList);   // <TodoList userId="42" /> — `cn` is injected
-```
-```ts
-// services/todos.ts — outside React
-import { getCodenotch } from 'codenotch-react';
-export async function loadTodos(userId: string) {
-    const result = await getCodenotch().startProcess('getTodos', 'start', { UserId: userId });
-    return result.output.todos;
-}
-```
-The environment (cluster URL, service name, language, translations…) is set up by `init(envVariables)`, which the Codenotch runtime calls automatically from the page hosting the application. You only call `init` yourself in custom hosting scenarios.
-## API overview
-| Member | Description |
-|--------|-------------|
-| `cn.env` | Readonly environment: `clusterUrl`, `serviceName`, `tenantName`, `accessToken`, `language`, `theme`, `i18n`, `appManifest`, `projectManifest`. |
-| `cn.i18n(key, ...args)` | Translate a key for the current language, filling `{0}`, `{1}`, … placeholders. |
-| `cn.startProcess(name, startNodeId, inputs)` | Start a server-side BPMN process and await its result. |
-| `cn.requestCnql(cnql, verbose?)` | Run a CNQL query (XML, SELECT-only) against the project's tables. |
-| `cn.listenSignal(signalId, callback)` | Subscribe to real-time signals emitted by BPMN processes. |
-| `cn.showDialog(node)` | Render a React node in a fullscreen modal dialog (own React root, unmounted on `close()`). |
-| `cn.setTheme(t)` / `cn.getTheme()` | `'light' \| 'dark'`; `setTheme` also toggles the class on `<html>` (Tailwind `dark:`). |
-| `cn.setLanguage(l)` / `cn.getLanguage()` / `cn.getLanguages()` | Current language and the languages declared in `manifest.json`. |
-| `cn.getProjectFile(path)` / `cn.getProjectFileUrl(path)` | Read/link a file of the deployed project. |
-| `cn.getUrlParams()` | Query-string parameters of the current URL as a plain object. |
-| `cn.uuid()` | Random UUID v4. |
-| `cn.getProjectManifest()` / `cn.getAppManifest()` | Project / application manifests. |
-Full signatures and JSDoc live in `dist/index.d.ts` (sources in `src/`).
-## Calling a BPMN process
-`processName` is the `.bpmn` file name without extension; `startNodeId` is the id of the start event to trigger (conventionally `'start'`); `inputs` are the input parameters declared by that start event. The result's `output` contains the parameters of the end event reached.
-```tsx
-const result = await cn.startProcess('getTodos', 'start', { UserId: userId });
-if (!result.isError) {
-    setTodos(result.output.todos);
-} else {
-    console.error(result.errorMessage);
-}
-```
-## Querying tables with CNQL
-CNQL is Codenotch's XML query language over the project's SQL tables (SELECT only — writes go through BPMN processes). The root `xmlns` must be the project's `serviceName`; each queried table's `Ref` attribute names its result set:
-```tsx
-const data = await cn.requestCnql(`
-    <CNQL xmlns="myproject" PageSize="10" PageIndex="0">
-        <Users Ref="results">
-            <Id />
-            <Email />
-            <IsAdmin Equal="true" />
-        </Users>
-    </CNQL>`);
-console.log(data.results); // [{ Id: '...', Email: '...' }, ...]
-```
-## Translations (i18n)
-Translations come from the project's `.i18n.csv` files and are injected into `cn.env.i18n` at startup. `cn.i18n(key, ...args)` translates for the current language and replaces `{0}`, `{1}`, … placeholders; it never throws — an unknown key is returned as-is (with a console warning).
-```tsx
-cn.i18n('welcome');               // "Bienvenue"
-cn.i18n('greeting', 'Ada', 3);    // "Bonjour Ada, 3 messages"  (from "Bonjour {0}, {1} messages")
-cn.setLanguage('en');             // switch language at runtime — every component using
-                                  // useCodenotch() / withCodenotch() re-renders
-```
-## Real-time signals
-BPMN processes can broadcast signals; subscribe from the UI with `listenSignal`:
-```tsx
-useEffect(() => {
-    let sub: IDisposable | undefined;
-    let cancelled = false;
-    getCodenotch().listenSignal('todosChanged', (signal) => refresh(signal.data))
-        .then(s => { if (cancelled) s.dispose(); else sub = s; });
-    return () => { cancelled = true; sub?.dispose(); };
-}, []);
-```
-Two details: the `cancelled` flag matters under React 19's StrictMode, which mounts / unmounts / remounts effects in development — without it the first subscription would leak when the cleanup runs before the promise resolves. And the effect uses `getCodenotch()` rather than the `cn` from `useCodenotch()`: the hook's object changes on every language/theme change, so listing it in the dependency array would re-subscribe on each change, while omitting it trips `react-hooks/exhaustive-deps`. `getCodenotch()` sidesteps both.
-## Dialogs
-```tsx
-const dialog = cn.showDialog(
-    <div className="bg-white dark:bg-gray-800 p-6 rounded shadow">
-        <p>{cn.i18n('confirm.message')}</p>
-        <button onClick={() => dialog.close()}>{cn.i18n('close')}</button>
-    </div>
-);
-```
-The dialog stays open until you call `dialog.close()`, which unmounts the React tree and removes the `<dialog>` element. The content is rendered in its own React root, so it does not share context (providers) with the calling component.
-## Type-safe processes and translation keys
-`startProcess` and `i18n` are typed through two registries, `ProcessRegistry` and `TranslationRegistry`, that the **Codenotch IDE fills by declaration merging**: it generates `typings/process.d.ts` and `typings/i18n.d.ts` in each project from the `.bpmn` and `.i18n.csv` files (never edit those files — refresh the project instead). The generated files look like:
-```ts
-import 'codenotch-react';
-declare module 'codenotch-react' {
-    interface TranslationRegistry {
-        'welcome': [];
-        'greeting': [arg1: any, arg2: any];
-    }
-    interface ProcessRegistry {
-        'getTodos': {
-            nodes: { 'start': { UserId: string } };
-            output: { todos: any[] };
-        };
-    }
-}
-```
-With these in the compilation, keys, inputs and outputs are strictly checked and autocompleted. **Without them** (project compiled outside the IDE), the registries are empty and both methods gracefully fall back to plain `string` keys and untyped arguments — the code still compiles.
-## Notes for AI assistants
-- The complete typed API surface is in `dist/index.d.ts`; the readable implementation ships in `src/` (entry point `src/index.ts`).
-- `useCodenotch()` is a real hook (hook rules apply; re-renders on language/theme change). In class components use `withCodenotch(Component)` and read `this.props.cn`; in event handlers, services, plain modules or effects use `getCodenotch()`. Never call `useCodenotch()` outside a function component / custom hook.
-- The object returned by `useCodenotch()` changes when the environment changes: fine in `useMemo` deps, but in `useEffect` prefer `getCodenotch()` unless the effect should re-run on language/theme change.
-- Never hand-edit a project's `typings/i18n.d.ts` / `typings/process.d.ts`: they are regenerated by the Codenotch IDE.
-- Codenotch apps are React 19 + Tailwind CSS (automatic JSX runtime — no `import React` needed for JSX); CNQL is SELECT-only (writes go through BPMN processes via `startProcess`).

package/src/core/ProcessUtils.ts DELETED Viewed

@@ -1,86 +0,0 @@
-import { v4 } from "uuid";
-import { IProcessCallbacks } from "../models/Misc";
-import { IProcessResult } from "../models/Codenotch";
-/**
- * static class mainly containing a method to start processes
- */
-export default class ProcessUtils {
-    public static async startProcess(subscribeFunc: (processInstanceId: string, callbacks: IProcessCallbacks) => Promise<void>, clusterUrl: string, tenantName: string, projectName: string, processId: string, processInput: any, processInstanceId?: string, startNodeId?: string, token?: string): Promise<IProcessResult>
-	{
-        let instanceId = processInstanceId ? processInstanceId : v4();
-        return new Promise(async (resolve, reject) => {
-            try
-            {
-                // Another class/component is responsible for listening to processes' states and calling back when they finish
-                await subscribeFunc(instanceId, {
-                    onCallback: (callback) => {
-                        //TODO check redirect ?
-                    },
-                    onOver: (processResult) => {
-                        // The process has finished
-                        resolve(processResult);
-                    },
-                })
-                // Create a new process instance
-                await ProcessUtils.launchMainProcess(clusterUrl, tenantName, projectName, processId, processInput, instanceId, startNodeId, token);
-            }
-            catch(err: any)
-            {
-                console.error(err);
-                let processResult: IProcessResult = {
-                    isError: true,
-                    processInstanceId: instanceId,
-                    output: {},
-                    errorMessage: err.message
-                }
-                resolve(processResult);
-            }
-        });
-	}
-    private static async launchMainProcess(clusterUrl: string, tenantName: string, projectName: string, processId: string, processInput: any, processInstanceId: string, startNodeId?: string, token?: string) {
-        console.log("launching main process");
-        let input = processInput ? processInput : {};
-        // We launch the process with an http request
-        let url = `${clusterUrl}/${projectName.toLowerCase()}/processes/${processId}/instances`;
-        let body = {
-            id: processInstanceId,
-            input: input,
-            startNode: startNodeId
-        }
-        let requestHeaders = new Headers();
-        requestHeaders.set('Content-Type', 'application/json');
-        if(token && token !== "")
-        {
-            requestHeaders.set(`${tenantName}AccessToken`, token);
-        }
-        const response = await fetch(url, {
-            method: 'POST',
-            credentials: 'include', // forward auth cookiesbody
-            body: JSON.stringify(body),
-            headers: requestHeaders
-        })
-        if(!response.ok)
-        {
-            // Something went wrong
-            let errorMessage = await response.text();
-            throw new Error(errorMessage)
-        }
-    }
-}

package/src/core/SignalR.ts DELETED Viewed

@@ -1,375 +0,0 @@
-import { HttpTransportType, HubConnectionBuilder, HubConnectionState, LogLevel } from "@microsoft/signalr";
-import { v4 } from "uuid";
-import { IProcessCallbacks, ICodenotchSignal } from "../models/Misc";
-import { IProcessResult } from "../models/Codenotch";
-export class SignalR {
-    private _connection: signalR.HubConnection | null;
-    private _hubUrl: string;
-    private _accessToken: string | undefined;
-    // The callbacks coming from components when a signal is received
-    // Also used on the root component to keep track of which signals we listen to
-    private _signalCallbacks: {[signalId: string]: {[subscriptionId: string]: (signal: ICodenotchSignal) => void} };
-    // Store callbacks of ongoing processes
-    private _processCallbacks: {[processInstanceId: string]: IProcessCallbacks};
-    private _inactivityTimer: NodeJS.Timeout | null;
-    private _unsubscribeTimers: {[signalId: string]: NodeJS.Timeout} = {};
-    private _isConnecting: boolean = false;
-    private _pendingConnectionPromises: Array<{ resolve: () => void; reject: (error: Error) => void }> = [];
-    // Determines if connection should be kept alive even if there are no subscriptions
-    private _keepAlive: boolean;
-    public constructor(clusterUrl: string, serviceName: string, keepAlive: boolean, accessToken?: string)
-    {
-        this._hubUrl = `${clusterUrl}/${serviceName}/exec`;
-        this._accessToken = accessToken;
-        this._connection = null;
-        this._signalCallbacks = {};
-        this._processCallbacks = {};
-        this._inactivityTimer = null;
-        this._keepAlive = keepAlive;
-    }
-    async connect() {
-        console.log(`SignalR establishing connection...`)
-        this._isConnecting = true;
-        // Here we inject the access token if defined
-        let options: signalR.IHttpConnectionOptions = this._accessToken ? { accessTokenFactory: () => this._accessToken! } : {};
-        // Skip negotiation and only use websockets
-        // This allows us to have multiple SignalR server without sticky sessions
-        // But it won't work in the rare cases where websockets are not supported
-        options.skipNegotiation = true;
-        options.transport = HttpTransportType.WebSockets;
-        //TODO if the server has multi instances, and the one we are connected fails, do sticky sessions prevent us from connecting to a healthy instance ?
-        this._connection = new HubConnectionBuilder()
-            .withUrl(this._hubUrl, options)
-            .withAutomaticReconnect([0, 1000, 3000, 5000, 10000, 30000, 60000, 90000]) // If the server is a single instance and decide to change node, it might take a little while
-            .configureLogging(LogLevel.Error)
-            .build();
-        this._connection.off("ReceiveSignal");
-        this._connection.off("ReceiveLog");
-        this._connection.off("ReceiveCallback");
-        this._connection.off("ReceiveProcessOver");
-        // On Signal
-        this._connection.on("ReceiveSignal", (signal: ICodenotchSignal) => this.onSignalReceived(signal));
-        // On log
-        this._connection.on("ReceiveLog", (log: string) => {
-            console.log(log);
-        });
-        // On callback received from process
-        //TODO only used to set wec content and redirect, do we still need those ?
-        this._connection.on("ReceiveCallback", (callback) => this.onProcessCallbackReceived(callback));
-        // On process completed
-        this._connection.on("ReceiveProcessOver", (processResult: IProcessResult) => this.onProcessOverReceived(processResult));
-        this._connection.onclose(
-            (error) => console.log(`disconnected: ${error ? error.message : "no error"}`)
-        );
-        this._connection.onreconnected(
-            () => this.resolvePendingRequests()
-        );
-        try
-        {
-            await this._connection.start();
-            console.log(`SignalR connection established`)
-            this.resolvePendingRequests();
-            this._isConnecting = false;
-        }
-        catch(err: any)
-        {
-            console.log(`SignalR connection error: ${err}`)
-            this.rejectPendingRequests(err);
-            this._isConnecting = false;
-        }
-    }
-    private resolvePendingRequests()
-    {
-        if(this._pendingConnectionPromises.length > 0)
-        {
-            console.log(`Resolving ${this._pendingConnectionPromises.length} pending connection promises`);
-        }
-        for(let p of this._pendingConnectionPromises)
-        {
-            p?.resolve();
-        }
-    }
-    private rejectPendingRequests(error: Error): void {
-        if(this._pendingConnectionPromises.length > 0)
-        {
-            console.log(`Rejecting ${this._pendingConnectionPromises.length} pending connection promises`);
-        }
-        for(let p of this._pendingConnectionPromises)
-        {
-            p?.reject(error);
-        }
-    }
-    private async ensureConnected() {
-        if(this._inactivityTimer)
-        {
-            // cancel disconnection
-            clearTimeout(this._inactivityTimer);
-            this._inactivityTimer = null;
-        }
-        if(this._connection && this._connection.state === HubConnectionState.Connected)
-        {
-            return Promise.resolve();
-        }
-        console.log(`SignalR not currently connected, waiting on connection...`)
-        const connectionPromise = new Promise<void>((resolve, reject) => {
-            this._pendingConnectionPromises.push({ resolve, reject });
-        });
-        if (!this._isConnecting) {
-            this.connect();
-        }
-        // Return a promise that will resolve when the connection is established
-        return connectionPromise;
-    }
-    private onSignalReceived(signal: ICodenotchSignal) {
-        try {
-            console.log(`Received signal '${signal.signalId}'`)
-            console.log(signal);
-            // parse the eventual data in the signal
-            if(signal.data)
-            {
-                try
-                {
-                    signal.data = JSON.parse(signal.data);
-                }
-                catch {
-                    // Data is not json but might still be valid
-                }
-            }
-            // If signal id contains multiple paths, trigger each one
-            var signalPaths = this.getSignalPaths(signal.signalId);
-            for(let p of signalPaths)
-            {
-                if(this._signalCallbacks[p])
-                {
-                    for(let callback of Object.values(this._signalCallbacks[p]))
-                    {
-                        callback(signal);
-                    }
-                }
-            }
-        }
-        catch (ex) {
-            console.log(`An exception occured during 'ReceiveSignal' callback:`);
-            console.log(ex);
-        }
-    }
-    private getSignalPaths(signalId: string): string[]
-    {
-        // Signals can be segmented using '.', each segment corresponds to a more specific subject
-        // Subscribers can subscribe to a very specific signal or to a more general topic
-        // eg. Signal ref : invoice.update.0000-1111-2222-3333, will be received by subscribers on:
-        //  -> 'invoice'
-        //  -> 'invoice.update'
-        //  -> 'invoice.update.0000-1111-2222-3333'
-        var signalPaths:string[] = [];
-        if(!signalId || signalId === '')
-            return signalPaths;
-        var segments = signalId.split('.');
-        for (let i = 0; i < segments.length; i++)
-        {
-            signalPaths.push(segments.slice(0, i + 1).join('.')); // "path" from index 0 to i
-        }
-        return signalPaths;
-    }
-    private onProcessCallbackReceived(callback: {processInstanceId: string }) {
-        // Trigger the corresponding callback (set in ProcessUtils before launching the process)
-        if(this._processCallbacks[callback.processInstanceId])
-        {
-            this._processCallbacks[callback.processInstanceId].onCallback(callback)
-        }
-    }
-    private onProcessOverReceived(processResult: IProcessResult) {
-        // Trigger the corresponding callback (set in ProcessUtils before launching the process)
-        if(this._processCallbacks[processResult.processInstanceId])
-        {
-            this._processCallbacks[processResult.processInstanceId].onOver(processResult)
-            // Clean it, now that the process is over we should not receive anymore callbacks
-            delete this._processCallbacks[processResult.processInstanceId];
-            this.disconnectIfInactive();
-        }
-    }
-    async subscribeToProcessInstance(processInstanceId: string, callbacks: IProcessCallbacks) {
-        if(this._processCallbacks[processInstanceId])
-        {
-            // Already subscribed
-            return;
-        }
-        await this.ensureConnected();
-        try
-        {
-            await this._connection!.invoke("SubscribeToInstanceEvents", processInstanceId);
-            // Setup callbacks
-            this._processCallbacks[processInstanceId] = callbacks;
-        }
-        catch(err)
-        {
-            console.error(`Couldn't subscribe to process '${processInstanceId}', : ${err}`)
-        }
-    }
-    async subscribeToSignal(signalId: string, callback: (signal: ICodenotchSignal) => void): Promise<() => Promise<void>> {
-        console.log(`subscribeToSignal: signalId:${signalId}`);
-        if (!signalId || signalId === "")
-            return () => Promise.resolve();
-        await this.ensureConnected();
-        if(this._unsubscribeTimers[signalId])
-        {
-            // cancel eventual unsubscription
-            clearTimeout(this._unsubscribeTimers[signalId]);
-            delete this._unsubscribeTimers[signalId];
-        }
-        if(!this._signalCallbacks[signalId])
-        {
-            // Create the subscription
-            try
-            {
-                await this._connection!.invoke("SubscribeToSignal", signalId);
-                // Remember which signals we are subscribed so we don't subscribe twice
-                if(!this._signalCallbacks[signalId])
-                {
-                    this._signalCallbacks[signalId] = {};
-                }
-            }
-            catch(err)
-            {
-                throw `Couldn't subscribe to signal '${signalId}', : ${err}`;
-            }
-        }
-        // Generate a new id to keep track of each subscription
-        let subscriptionId = v4();
-        this._signalCallbacks[signalId][subscriptionId] = callback;
-        // Return the unsubscribe function
-        return async () => await this.unsubscribeFromSignal(signalId, subscriptionId);
-    }
-    async unsubscribeFromSignal(signalId: string, subscriptionId: string)
-    {
-        console.log(`unsubscribeFromSignal: signalId:${signalId}, subscriptionId:${subscriptionId}`);
-        if(!this._signalCallbacks[signalId])
-        {
-            return;
-        }
-        delete this._signalCallbacks[signalId][subscriptionId];
-        // From this point we won't send events to the component who just unsubscribed, but we are still subscribed to the signal on the server so we'll recieve new signals
-        this.unsubscribeFromServerIfNoMoreSubscriptions(signalId);
-        // If no more subscriptions, we can disconnect from the server
-        this.disconnectIfInactive();
-    }
-    private unsubscribeFromServerIfNoMoreSubscriptions(signalId: string)
-    {
-        if(Object.keys(this._signalCallbacks[signalId]).length === 0)
-        {
-            delete this._signalCallbacks[signalId];
-            // No more subscriptions for this signal, we can unsubscribe from the server
-            // but in order to not send too many requests, we will wait a little bit before actually unsubscribing, the client might come back to the tab that need this signal in a few seconds
-            this._unsubscribeTimers[signalId] = setTimeout(() => this.unsubscribeSignalServer(signalId), 1 * 60 * 1000);
-        }
-    }
-    private async unsubscribeSignalServer(signalId: string)
-    {
-        console.log(`unsubscribeSignalServer: signalId:${signalId}`);
-        await this._connection!.invoke("UnsubscribeFromSignal", signalId);
-    }
-    private disconnectIfInactive()
-    {
-        if(this._keepAlive)
-            return;
-        if(Object.keys(this._signalCallbacks).length === 0 && Object.keys(this._processCallbacks).length === 0)
-        {
-            // No more subscriptions, disconnect from the server after a little while (5 minutes) to save resources
-            this._inactivityTimer = setTimeout(() => this.disconnect(), 5 * 60 * 1000);
-            console.log("SignalR has no more active subscriptions, will disconnect in 5 minutes...");
-        }
-    }
-    public disconnect(): void {
-        if (this._connection) {
-            this._connection.off("ReceiveCallback");
-            this._connection.off("ReceiveProcessOver");
-            this._connection.off("ReceiveSignal");
-            this._connection.off("ReceiveLog");
-            this._connection.stop();
-            this._connection = null;
-        }
-    }
-}