@simpleplatform/sdk 1.0.0

package/dist/graphql.d.ts

@@ -0,0 +1,33 @@
+import type { Context } from './types';
+/**
+ * Executes a GraphQL query with variables and returns the data directly.
+ * This function communicates with the host system's database action and handles
+ * JSON marshaling, response processing, and error handling internally.
+ *
+ * @param query The GraphQL query string to execute.
+ * @param variables Query variables as a map or object.
+ * @param context The execution context for the query.
+ * @returns A promise that resolves with the GraphQL query result data.
+ * @throws Will throw an error if the query fails or the host returns an error.
+ */
+export declare function execute<T = any>(query: string, variables: any, context: Context): Promise<T>;
+/**
+ * Executes a GraphQL mutation operation.
+ * It will throw an error if a query operation is passed.
+ *
+ * @param mutation The GraphQL mutation string.
+ * @param variables The variables for the mutation.
+ * @param context The execution context.
+ * @returns A promise that resolves with the mutation result.
+ */
+export declare function mutate<T = any>(mutation: string, variables: any, context: Context): Promise<T>;
+/**
+ * Executes a GraphQL query operation.
+ * It will throw an error if a mutation operation is passed.
+ *
+ * @param query The GraphQL query string.
+ * @param variables The variables for the query.
+ * @param context The execution context.
+ * @returns A promise that resolves with the query result.
+ */
+export declare function query<T = any>(query: string, variables: any, context: Context): Promise<T>;

package/dist/graphql.js

@@ -0,0 +1,56 @@
+import { execute as hostExecute } from './host';
+/**
+ * Executes a GraphQL query with variables and returns the data directly.
+ * This function communicates with the host system's database action and handles
+ * JSON marshaling, response processing, and error handling internally.
+ *
+ * @param query The GraphQL query string to execute.
+ * @param variables Query variables as a map or object.
+ * @param context The execution context for the query.
+ * @returns A promise that resolves with the GraphQL query result data.
+ * @throws Will throw an error if the query fails or the host returns an error.
+ */
+export async function execute(query, variables, context) {
+    if (!query) {
+        throw new Error('query is required for GraphQL execution');
+    }
+    const response = await hostExecute('action:db/execute', { query, variables }, context);
+    if (!response.ok) {
+        // eslint-disable-next-line no-console
+        console.log('[GraphQL] response.error:', JSON.stringify(response.error, null, 2));
+        // eslint-disable-next-line no-console
+        console.log('[GraphQL] response.data:', JSON.stringify(response.data, null, 2));
+        throw new Error(response.error?.message ?? 'GraphQL query failed');
+    }
+    return response.data;
+}
+/**
+ * Executes a GraphQL mutation operation.
+ * It will throw an error if a query operation is passed.
+ *
+ * @param mutation The GraphQL mutation string.
+ * @param variables The variables for the mutation.
+ * @param context The execution context.
+ * @returns A promise that resolves with the mutation result.
+ */
+export async function mutate(mutation, variables, context) {
+    if (!mutation.trim().startsWith('mutation')) {
+        throw new Error('A query was passed to the `mutate` method. Use the `query` method instead.');
+    }
+    return execute(mutation, variables, context);
+}
+/**
+ * Executes a GraphQL query operation.
+ * It will throw an error if a mutation operation is passed.
+ *
+ * @param query The GraphQL query string.
+ * @param variables The variables for the query.
+ * @param context The execution context.
+ * @returns A promise that resolves with the query result.
+ */
+export async function query(query, variables, context) {
+    if (query.trim().startsWith('mutation')) {
+        throw new Error('A mutation was passed to the `query` method. Use the `mutate` method instead.');
+    }
+    return execute(query, variables, context);
+}

package/dist/host.d.ts

@@ -0,0 +1,28 @@
+import type { Context, SimpleResponse } from './types';
+/**
+ * Executes an action synchronously on the host system and returns the response.
+ *
+ * NOTE: The memory model for this execution is that the entire WASM instance is
+ * ephemeral. Memory is allocated for this single execution and then discarded
+ * when the instance is terminated. Therefore, a manual memory reset is not required.
+ *
+ * This function has two internal implementations selected at build time:
+ * 1. ASYNC_BUILD = true: For browsers, uses Asyncify to pause/resume execution.
+ * 2. ASYNC_BUILD = false: For Elixir, uses a synchronous call-and-get-result pattern.
+ */
+export declare function execute<T = any>(actionName: string, params: any, context: Context): SimpleResponse<T>;
+/**
+ * Executes an action asynchronously on the host system (fire-and-forget).
+ */
+export declare function executeAsync(actionName: string, params: any, context: Context): void;
+/**
+ * Retrieves the initial context payload from the host. This function orchestrates
+ * the "pull" mechanism required by the execution environment.
+ *
+ * It first asks the host for the payload size, then allocates memory within
+ * the WASM module, and finally asks the host to write the payload into the
+ * allocated buffer.
+ *
+ * @returns A Uint8Array containing the context payload.
+ */
+export declare function getContext(): Uint8Array;

package/dist/host.js

@@ -0,0 +1,148 @@
+import { allocate, deallocate, decoder, readBufferSlice, stringToPtr } from './internal/memory';
+/**
+ * Executes an action synchronously on the host system and returns the response.
+ *
+ * NOTE: The memory model for this execution is that the entire WASM instance is
+ * ephemeral. Memory is allocated for this single execution and then discarded
+ * when the instance is terminated. Therefore, a manual memory reset is not required.
+ *
+ * This function has two internal implementations selected at build time:
+ * 1. ASYNC_BUILD = true: For browsers, uses Asyncify to pause/resume execution.
+ * 2. ASYNC_BUILD = false: For Elixir, uses a synchronous call-and-get-result pattern.
+ */
+export function execute(actionName, params, context) {
+    // We must track the pointers for the parameters so we can free them after the call.
+    // They are declared here to be accessible in the `finally` block.
+    let actionNamePtr = 0;
+    let actionNameLen = 0;
+    let paramsPtr = 0;
+    let paramsLen = 0;
+    let contextPtr = 0;
+    let contextLen = 0;
+    try {
+        const paramsJSON = JSON.stringify(params ?? null);
+        const contextJSON = JSON.stringify(context);
+        [actionNamePtr, actionNameLen] = stringToPtr(actionName);
+        [paramsPtr, paramsLen] = stringToPtr(paramsJSON);
+        [contextPtr, contextLen] = stringToPtr(contextJSON);
+        if (__ASYNC_BUILD__) {
+            // --- ASYNCIFY-AWARE PATH (FOR BROWSER) ---
+            let responsePtr = 0;
+            let responseLen = 0;
+            try {
+                // State 2 is "Rewinding". This check implements the stateful "double call"
+                // pattern required by Asyncify.
+                if (asyncify_get_state() === 2) {
+                    // This is the second call, during the rewind. We just need to stop the
+                    // rewind so that normal execution can resume.
+                    asyncify_stop_rewind();
+                }
+                else {
+                    // This is the first call. Call the host to start the async operation.
+                    // The host will then trigger the unwind.
+                    __host.call(actionNamePtr, actionNameLen, paramsPtr, paramsLen, contextPtr, contextLen);
+                }
+                // --- EXECUTION PAUSES HERE OR CONTINUES AFTER REWIND IS STOPPED ---
+                // The host has placed the response in memory. Read it using pointers
+                // retrieved from the Javy plugin.
+                responsePtr = __wasm.get_response_ptr();
+                responseLen = __wasm.get_response_len();
+                const resultBytes = readBufferSlice(responsePtr, responseLen);
+                const resultJSON = decoder.decode(resultBytes);
+                // Immediately clear the response buffer pointers in the Javy plugin to
+                // prevent reading stale data on subsequent nested calls.
+                __wasm.clear_response_buffer();
+                return JSON.parse(resultJSON);
+            }
+            finally {
+                // 1. Free the result buffer allocated by the host.
+                if (responsePtr > 0) {
+                    deallocate(responsePtr, responseLen);
+                }
+            }
+        }
+        else {
+            // --- SYNCHRONOUS PATH (FOR ELIXIR BACKEND) ---
+            let resultPtr = 0;
+            let resultLen = 0;
+            try {
+                // 1. Make the synchronous call. The host now holds the result.
+                __host.call(actionNamePtr, actionNameLen, paramsPtr, paramsLen, contextPtr, contextLen);
+                // 2. Ask the host for the size of the result.
+                resultLen = __host.getExecutionResultSize();
+                if (resultLen === 0) {
+                    return { error: { message: 'Host returned an empty result.' }, ok: false };
+                }
+                // 3. Allocate memory inside WASM for the result.
+                resultPtr = allocate(resultLen);
+                // 4. Ask the host to write the result into our buffer.
+                __host.getExecutionResult(resultPtr);
+                // 5. Read the result from our buffer and return it.
+                const resultBytes = readBufferSlice(resultPtr, resultLen);
+                const resultJSON = decoder.decode(resultBytes);
+                return JSON.parse(resultJSON);
+            }
+            finally {
+                // Free the result buffer allocated by us.
+                if (resultPtr > 0) {
+                    deallocate(resultPtr, resultLen);
+                }
+            }
+        }
+    }
+    finally {
+        // 2. Free the parameter buffers we allocated before the host call.
+        if (actionNamePtr > 0) {
+            deallocate(actionNamePtr, actionNameLen);
+        }
+        if (paramsPtr > 0) {
+            deallocate(paramsPtr, paramsLen);
+        }
+        if (contextPtr > 0) {
+            deallocate(contextPtr, contextLen);
+        }
+    }
+}
+/**
+ * Executes an action asynchronously on the host system (fire-and-forget).
+ */
+export function executeAsync(actionName, params, context) {
+    const paramsJSON = JSON.stringify(params ?? null);
+    const contextJSON = JSON.stringify(context);
+    const [actionNamePtr, actionNameLen] = stringToPtr(actionName);
+    const [paramsPtr, paramsLen] = stringToPtr(paramsJSON);
+    const [contextPtr, contextLen] = stringToPtr(contextJSON);
+    // Make the asynchronous (fire-and-forget) call to the host.
+    __host.cast(actionNamePtr, actionNameLen, paramsPtr, paramsLen, contextPtr, contextLen);
+}
+/**
+ * Retrieves the initial context payload from the host. This function orchestrates
+ * the "pull" mechanism required by the execution environment.
+ *
+ * It first asks the host for the payload size, then allocates memory within
+ * the WASM module, and finally asks the host to write the payload into the
+ * allocated buffer.
+ *
+ * @returns A Uint8Array containing the context payload.
+ */
+export function getContext() {
+    // Ask the host for the size of the data.
+    const size = __host.getContextSize();
+    if (size === 0) {
+        return new Uint8Array(0);
+    }
+    // Allocate memory for the data inside the WASM module's buffer.
+    const ptr = allocate(size);
+    let buffer;
+    try {
+        // Ask the host to write the data into the allocated memory region.
+        __host.getContext(ptr);
+        // Now that the data is in our memory, create a slice to read it.
+        buffer = readBufferSlice(ptr, size);
+    }
+    finally {
+        // Free the memory we allocated now that the data is in a JS-owned buffer.
+        deallocate(ptr, size);
+    }
+    return buffer;
+}

package/dist/http.d.ts

@@ -0,0 +1,26 @@
+import type { Context } from './types';
+/**
+ * Represents the configuration for an HTTP request.
+ */
+export interface HttpRequest {
+    body?: any;
+    headers?: Record<string, string>;
+    method?: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+    url: string;
+}
+export declare function del<T = any>(url: string, headers: Record<string, string>, context: Context): Promise<T>;
+/**
+ * Executes an HTTP request and returns the response data directly.
+ * This provides an ergonomic API for HTTP operations by handling host communication
+ * and error checking internally.
+ *
+ * @param request The HTTP request configuration.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the HTTP response data.
+ * @throws Will throw an error if the request fails or the host returns an error.
+ */
+export declare function fetch<T = any>(request: HttpRequest, context: Context): Promise<T>;
+export declare function get<T = any>(url: string, headers: Record<string, string>, context: Context): Promise<T>;
+export declare function patch<T = any>(url: string, body: any, headers: Record<string, string>, context: Context): Promise<T>;
+export declare function post<T = any>(url: string, body: any, headers: Record<string, string>, context: Context): Promise<T>;
+export declare function put<T = any>(url: string, body: any, headers: Record<string, string>, context: Context): Promise<T>;

package/dist/http.js

@@ -0,0 +1,42 @@
+import { execute as hostExecute } from './host';
+export async function del(url, headers, context) {
+    return fetch({ headers, method: 'DELETE', url }, context);
+}
+/**
+ * Executes an HTTP request and returns the response data directly.
+ * This provides an ergonomic API for HTTP operations by handling host communication
+ * and error checking internally.
+ *
+ * @param request The HTTP request configuration.
+ * @param context The execution context for the request.
+ * @returns A promise that resolves with the HTTP response data.
+ * @throws Will throw an error if the request fails or the host returns an error.
+ */
+export async function fetch(request, context) {
+    if (!request.url) {
+        throw new Error('URL is required for HTTP request');
+    }
+    const hostRequest = {
+        body: request.body ? JSON.stringify(request.body) : undefined,
+        headers: request.headers,
+        method: request.method ?? 'GET',
+        url: request.url,
+    };
+    const response = await hostExecute('action:http/fetch', hostRequest, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message ?? 'HTTP request failed');
+    }
+    return response.data;
+}
+export async function get(url, headers, context) {
+    return fetch({ headers, method: 'GET', url }, context);
+}
+export async function patch(url, body, headers, context) {
+    return fetch({ body, headers, method: 'PATCH', url }, context);
+}
+export async function post(url, body, headers, context) {
+    return fetch({ body, headers, method: 'POST', url }, context);
+}
+export async function put(url, body, headers, context) {
+    return fetch({ body, headers, method: 'PUT', url }, context);
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import type { Context, SimpleRequest, SimpleResponse } from './types';
+import './internal/global';
+export * from './storage';
+export * from './types';
+/**
+ * Defines the signature for a user's action handler.
+ */
+export type Handler<TResult = any> = (request: Request) => Promise<TResult> | TResult;
+/**
+ * Represents an incoming action request with ergonomic access to its data.
+ * This class will be exposed as `simple.Request`.
+ */
+export declare class Request {
+    readonly context: Context;
+    readonly headers: Record<string, any>;
+    private readonly rawData;
+    constructor(simpleRequest: SimpleRequest);
+    /** Returns the raw data string from the request. */
+    data(): string;
+    /** Parses the request data JSON into a new object. */
+    parse<T>(): T;
+}
+declare function execute<T = any>(actionName: string, params: any, context: Context): SimpleResponse<T>;
+declare function executeAsync(actionName: string, params: any, context: Context): void;
+/**
+ * The main entry point for a Simple Logic action.
+ *
+ * This function provides a transparent developer experience by detecting the
+ * execution environment and choosing the optimal strategy.
+ *
+ * - In a synchronous environment (like the Elixir backend), it executes the
+ *   handler directly. With QuickJS's event loop enabled, it can now correctly
+ *   await async handlers and their host calls.
+ * - In an asynchronous, constrained environment (like the browser), it
+ *   automatically offloads the *entire bundled application script* to an
+ *   unconstrained script worker for execution.
+ *
+ * @returns In most environments, this function returns `Promise<void>` as it
+ *   signals completion via a fire-and-forget host call. However, when executed
+ *   inside the script worker (`__IS_WORKER_BUILD__`), it returns the `Promise`
+ *   from the user's handler. This is critical for allowing the script worker
+ *   to correctly `await` the completion of the user's async logic.
+ */
+declare function handle(handler: Handler): Promise<any>;
+declare const simple: {
+    Execute: typeof execute;
+    ExecuteAsync: typeof executeAsync;
+    Handle: typeof handle;
+    Request: typeof Request;
+};
+export default simple;

package/dist/index.js

@@ -0,0 +1,165 @@
+import * as host from './host';
+import './internal/global';
+export * from './storage';
+export * from './types';
+/**
+ * Represents an incoming action request with ergonomic access to its data.
+ * This class will be exposed as `simple.Request`.
+ */
+export class Request {
+    constructor(simpleRequest) {
+        this.context = simpleRequest.context;
+        this.headers = simpleRequest.headers;
+        this.rawData = simpleRequest.data ?? '';
+    }
+    /** Returns the raw data string from the request. */
+    data() {
+        return this.rawData;
+    }
+    /** Parses the request data JSON into a new object. */
+    parse() {
+        if (!this.rawData) {
+            throw new Error('no data to parse');
+        }
+        try {
+            return JSON.parse(this.rawData);
+        }
+        catch (e) {
+            throw new Error(`failed to parse data: ${e.message}`);
+        }
+    }
+}
+function execute(actionName, params, context) {
+    return host.execute(actionName, params, context);
+}
+// --- Internal Implementations ---
+function executeAsync(actionName, params, context) {
+    return host.executeAsync(actionName, params, context);
+}
+/**
+ * The main entry point for a Simple Logic action.
+ *
+ * This function provides a transparent developer experience by detecting the
+ * execution environment and choosing the optimal strategy.
+ *
+ * - In a synchronous environment (like the Elixir backend), it executes the
+ *   handler directly. With QuickJS's event loop enabled, it can now correctly
+ *   await async handlers and their host calls.
+ * - In an asynchronous, constrained environment (like the browser), it
+ *   automatically offloads the *entire bundled application script* to an
+ *   unconstrained script worker for execution.
+ *
+ * @returns In most environments, this function returns `Promise<void>` as it
+ *   signals completion via a fire-and-forget host call. However, when executed
+ *   inside the script worker (`__IS_WORKER_BUILD__`), it returns the `Promise`
+ *   from the user's handler. This is critical for allowing the script worker
+ *   to correctly `await` the completion of the user's async logic.
+ */
+async function handle(handler) {
+    // Context 2: We are inside the unconstrained script worker.
+    // This is the highest-priority check.
+    if (typeof __IS_WORKER_BUILD__ !== 'undefined' && __IS_WORKER_BUILD__) {
+        // The wrapper (`build.js`) is responsible for the try/catch block.
+        // The job of `handle` here is ONLY to parse the input and pass the
+        // resulting promise to the wrapper via the secure channel.
+        const inputText = readInputFromHost();
+        if (!inputText) {
+            // If setup fails, we must put a rejected promise on the channel.
+            const error = new Error('no input payload provided by the host environment');
+            if (globalThis.__SIMPLE_PROMISE_CHANNEL__) {
+                ;
+                globalThis.__SIMPLE_PROMISE_CHANNEL__.promise = Promise.reject(error);
+            }
+            // Re-throwing ensures the worker's main catch block can see the error too.
+            throw error;
+        }
+        const simpleReq = JSON.parse(inputText);
+        const request = new Request(simpleReq);
+        const resultPromise = Promise.resolve(handler(request));
+        if (!globalThis.__SIMPLE_PROMISE_CHANNEL__) {
+            throw new Error('CRITICAL: Script worker context is missing the promise channel.');
+        }
+        // This is the key: place the promise on the channel and exit synchronously.
+        ;
+        globalThis.__SIMPLE_PROMISE_CHANNEL__.promise = resultPromise;
+        return; // DO NOT return the promise here.
+    }
+    // All other contexts (WASM Loader, Elixir Backend) are handled below.
+    let context;
+    try {
+        const inputText = readInputFromHost();
+        if (!inputText) {
+            returnError('no input payload provided by the host environment', undefined);
+            return;
+        }
+        const simpleReq = JSON.parse(inputText);
+        context = simpleReq.context;
+        // Context 1: This is the initial WASM loader running in the browser.
+        // Its only job is to start the script worker.
+        if (__ASYNC_BUILD__) {
+            // --- ASYNC PATH (BROWSER) ---
+            // We are in the constrained WASM environment. We cannot run the async
+            // handler here. Instead, we use the pre-bundled user script string
+            // and send it to the host to be run in an unconstrained worker.
+            if (typeof __USER_SCRIPT_BUNDLE__ === 'undefined') {
+                throw new TypeError('CRITICAL: __USER_SCRIPT_BUNDLE__ is not defined in async build. Check the build script.');
+            }
+            const payload = { request: simpleReq };
+            const result = await host.execute('runtime/script:execute', {
+                payload,
+                script: __USER_SCRIPT_BUNDLE__,
+            }, context);
+            if (!result.ok) {
+                throw new Error(result.error?.message ?? 'Unconstrained script execution failed');
+            }
+            returnSuccess(result.data, context);
+            return;
+        }
+        // Context 3: This is the synchronous path for the Elixir backend.
+        const request = new Request(simpleReq);
+        const resultPromise = Promise.resolve(handler(request));
+        const result = await resultPromise;
+        returnSuccess(result, context);
+    }
+    catch (e) {
+        // This catch block is ONLY for the non-worker paths.
+        // Worker errors are handled by the try/catch in `script.worker.ts`.
+        returnError(e.message, context);
+    }
+}
+/**
+ * Transparently reads the initial payload from the host.
+ * This function is designed to work in two contexts:
+ * 1. Inside a WASM module, where it reads from the host via ABI calls.
+ * 2. Inside a standard JS script worker, where the host places the payload
+ *    on the global scope as `__SIMPLE_INITIAL_PAYLOAD__`.
+ */
+function readInputFromHost() {
+    if (globalThis.__SIMPLE_INITIAL_PAYLOAD__) {
+        // This global variable is set by the script.worker.ts before executing the user's bundle.
+        return JSON.stringify(globalThis.__SIMPLE_INITIAL_PAYLOAD__.request);
+    }
+    // Otherwise, we are in the main WASM module and must read from the host ABI.
+    const buffer = host.getContext();
+    return new TextDecoder().decode(buffer);
+}
+function returnError(message, context) {
+    const response = { data: null, errors: [message], ok: false };
+    // Provide a minimal, safe context if the original is not available.
+    const safeContext = context ?? { logic: { execution_id: 'unknown' } };
+    host.executeAsync('__done__', response, safeContext);
+}
+function returnSuccess(data, context) {
+    // With the async handle function, we no longer need to check for promises here.
+    const response = { data, errors: [], ok: true };
+    host.executeAsync('__done__', response, context);
+}
+// --- The Default Export Object ---
+// This creates the single `simple` object that users will import.
+const simple = {
+    Execute: execute,
+    ExecuteAsync: executeAsync,
+    Handle: handle,
+    Request,
+};
+export default simple;

package/dist/internal/global.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file This script is the first to be imported by the SDK. Its purpose is to
+ * polyfill the global scope of the JavaScript runtime with necessary APIs that
+ * may be missing or non-compliant in a minimal environment like Javy/QuickJS.
+ *
+ * This ensures that all other modules within the SDK can reliably use standard
+ * APIs like `TextEncoder` and `TextDecoder` as if they were in a browser,
+ * making the SDK portable and self-sufficient.
+ */

package/dist/internal/global.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * @file This script is the first to be imported by the SDK. Its purpose is to
+ * polyfill the global scope of the JavaScript runtime with necessary APIs that
+ * may be missing or non-compliant in a minimal environment like Javy/QuickJS.
+ *
+ * This ensures that all other modules within the SDK can reliably use standard
+ * APIs like `TextEncoder` and `TextDecoder` as if they were in a browser,
+ * making the SDK portable and self-sufficient.
+ */
+// We need polyfills in ANY environment that is not the dedicated script worker.
+// The script worker is a modern browser environment with these APIs built-in.
+// The Javy/QuickJS environment inside the main WASM module, however, is minimal
+// and needs them for host communication.
+if (typeof __IS_WORKER_BUILD__ === 'undefined' || !__IS_WORKER_BUILD__) {
+    // Use `require` to ensure the import is contained within the conditional
+    // block, making it easy for the bundler to tree-shake.
+    // eslint-disable-next-line ts/no-require-imports
+    const { TextDecoder: PolyfillDecoder, TextEncoder: PolyfillEncoder } = require('./polyfills');
+    // Check if TextEncoder is not available on the global object.
+    if (typeof globalThis.TextEncoder === 'undefined') {
+        // If it's missing, we attach our robust polyfill to the global scope.
+        globalThis.TextEncoder = PolyfillEncoder;
+    }
+    // Do the same for TextDecoder.
+    if (typeof globalThis.TextDecoder === 'undefined') {
+        globalThis.TextDecoder = PolyfillDecoder;
+    }
+}