@simpleplatform/sdk 1.0.0

package/dist/internal/memory.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview WebAssembly Memory Management Module
+ *
+ * Provides a high-level interface for managing WebAssembly linear memory operations.
+ * This module handles string-based data exchange between JavaScript and the WASM
+ * runtime through direct UTF-8 operations, avoiding unnecessary serialization overhead.
+ *
+ * ## Architecture
+ *
+ * The memory bridge operates on two main principles:
+ * - **Direct String Operations**: Strings are passed directly between JS and WASM
+ * - **UTF-8 Encoding**: All string data is handled as UTF-8 encoded bytes
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Allocate memory for a string
+ * const [ptr, len] = stringToPtr("Hello, World!")
+ *
+ * // Read data back from memory
+ * const data = readBufferSlice(ptr, len)
+ * ```
+ */
+/** Reusable TextDecoder instance for UTF-8 string decoding. */
+export declare const decoder: TextDecoder;
+/**
+ * Allocates a block of memory within the WebAssembly linear memory space.
+ *
+ * This function provides the primary interface for requesting memory from
+ * the WASM module's allocator. The returned pointer can be used for
+ * subsequent read/write operations.
+ *
+ * @param size - Number of bytes to allocate
+ * @returns Memory pointer (offset) to the allocated block
+ *
+ * @example
+ * ```typescript
+ * const ptr = allocate(1024) // Allocate 1KB
+ * ```
+ */
+export declare function allocate(size: number): number;
+/**
+ *
+ * @param ptr - Memory pointer to deallocate
+ * @param size -  Number of bytes to deallocate
+ *
+ * @example
+ * ```typescript
+ * deallocate(ptr, 1024) // Deallocate 1KB
+ * ```
+ */
+export declare function deallocate(ptr: number, size: number): void;
+/**
+ * Reads string data from WebAssembly memory and returns it as UTF-8 bytes.
+ *
+ * This function provides a safe interface for reading string data from
+ * WASM memory, with proper error handling and fallback behavior.
+ *
+ * @param ptr - Memory pointer to read from
+ * @param len - Number of bytes to read
+ * @returns UTF-8 encoded bytes of the string data
+ *
+ * @example
+ * ```typescript
+ * const data = readBufferSlice(ptr, len)
+ * const text = decoder.decode(data) // Convert back to string
+ * ```
+ */
+export declare function readBufferSlice(ptr: number, len: number): Uint8Array;
+/**
+ * Reads a string directly from WebAssembly memory.
+ *
+ * This is a convenience function that combines memory reading and UTF-8
+ * decoding in a single operation.
+ *
+ * @param ptr - Memory pointer to read from
+ * @param len - Number of bytes to read
+ * @returns The decoded UTF-8 string
+ *
+ * @example
+ * ```typescript
+ * const text = readString(ptr, len)
+ * ```
+ */
+export declare function readString(ptr: number, len: number): string;
+/**
+ * Writes a JavaScript string to WebAssembly memory and returns its location.
+ *
+ * This function handles the complete process of:
+ * 1. Calculating the UTF-8 byte length of the string
+ * 2. Allocating sufficient memory in the WASM linear memory
+ * 3. Writing the string data to the allocated location
+ *
+ * @param str - The string to write to memory
+ * @returns A tuple containing [pointer, byte_length]
+ *
+ * @example
+ * ```typescript
+ * const [ptr, len] = stringToPtr("Hello, World!")
+ * // ptr points to the string data, len is the byte length
+ * ```
+ */
+export declare function stringToPtr(str: string): [number, number];

package/dist/internal/memory.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview WebAssembly Memory Management Module
+ *
+ * Provides a high-level interface for managing WebAssembly linear memory operations.
+ * This module handles string-based data exchange between JavaScript and the WASM
+ * runtime through direct UTF-8 operations, avoiding unnecessary serialization overhead.
+ *
+ * ## Architecture
+ *
+ * The memory bridge operates on two main principles:
+ * - **Direct String Operations**: Strings are passed directly between JS and WASM
+ * - **UTF-8 Encoding**: All string data is handled as UTF-8 encoded bytes
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Allocate memory for a string
+ * const [ptr, len] = stringToPtr("Hello, World!")
+ *
+ * // Read data back from memory
+ * const data = readBufferSlice(ptr, len)
+ * ```
+ */
+// =============================================================================
+// TEXT ENCODING UTILITIES
+// =============================================================================
+/** Reusable TextEncoder instance for UTF-8 string encoding. */
+const encoder = new TextEncoder();
+/** Reusable TextDecoder instance for UTF-8 string decoding. */
+export const decoder = new TextDecoder('utf-8');
+// =============================================================================
+// MEMORY ALLOCATION
+// =============================================================================
+/**
+ * Allocates a block of memory within the WebAssembly linear memory space.
+ *
+ * This function provides the primary interface for requesting memory from
+ * the WASM module's allocator. The returned pointer can be used for
+ * subsequent read/write operations.
+ *
+ * @param size - Number of bytes to allocate
+ * @returns Memory pointer (offset) to the allocated block
+ *
+ * @example
+ * ```typescript
+ * const ptr = allocate(1024) // Allocate 1KB
+ * ```
+ */
+export function allocate(size) {
+    return __wasm.alloc(size);
+}
+// =============================================================================
+// STRING MEMORY OPERATIONS
+// =============================================================================
+/**
+ *
+ * @param ptr - Memory pointer to deallocate
+ * @param size -  Number of bytes to deallocate
+ *
+ * @example
+ * ```typescript
+ * deallocate(ptr, 1024) // Deallocate 1KB
+ * ```
+ */
+export function deallocate(ptr, size) {
+    __wasm.dealloc(ptr, size);
+}
+/**
+ * Reads string data from WebAssembly memory and returns it as UTF-8 bytes.
+ *
+ * This function provides a safe interface for reading string data from
+ * WASM memory, with proper error handling and fallback behavior.
+ *
+ * @param ptr - Memory pointer to read from
+ * @param len - Number of bytes to read
+ * @returns UTF-8 encoded bytes of the string data
+ *
+ * @example
+ * ```typescript
+ * const data = readBufferSlice(ptr, len)
+ * const text = decoder.decode(data) // Convert back to string
+ * ```
+ */
+export function readBufferSlice(ptr, len) {
+    if (len === 0) {
+        return new Uint8Array(0);
+    }
+    try {
+        const str = __wasm.read_string(ptr, len);
+        return encoder.encode(str);
+    }
+    catch (error) {
+        console.error(`Memory read failed at ptr=${ptr}, len=${len}:`, error);
+        return new Uint8Array(0);
+    }
+}
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+/**
+ * Reads a string directly from WebAssembly memory.
+ *
+ * This is a convenience function that combines memory reading and UTF-8
+ * decoding in a single operation.
+ *
+ * @param ptr - Memory pointer to read from
+ * @param len - Number of bytes to read
+ * @returns The decoded UTF-8 string
+ *
+ * @example
+ * ```typescript
+ * const text = readString(ptr, len)
+ * ```
+ */
+export function readString(ptr, len) {
+    if (len === 0) {
+        return '';
+    }
+    try {
+        return __wasm.read_string(ptr, len);
+    }
+    catch (error) {
+        console.error(`String read failed at ptr=${ptr}, len=${len}:`, error);
+        return '';
+    }
+}
+/**
+ * Writes a JavaScript string to WebAssembly memory and returns its location.
+ *
+ * This function handles the complete process of:
+ * 1. Calculating the UTF-8 byte length of the string
+ * 2. Allocating sufficient memory in the WASM linear memory
+ * 3. Writing the string data to the allocated location
+ *
+ * @param str - The string to write to memory
+ * @returns A tuple containing [pointer, byte_length]
+ *
+ * @example
+ * ```typescript
+ * const [ptr, len] = stringToPtr("Hello, World!")
+ * // ptr points to the string data, len is the byte length
+ * ```
+ */
+export function stringToPtr(str) {
+    if (str.length === 0) {
+        return [allocate(0), 0];
+    }
+    const bytes = encoder.encode(str);
+    const ptr = allocate(bytes.length);
+    __wasm.write_string(ptr, str);
+    return [ptr, bytes.length];
+}

package/dist/internal/polyfills.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file Provides robust, production-quality polyfills for TextEncoder and TextDecoder.
+ * The logic is adapted from a public-domain UTF-8 implementation to ensure correctness
+ * and full Unicode support, including surrogate pairs.
+ *
+ * The Javy runtime has partial/non-compliant support for these APIs, so providing
+ * our own implementation makes the SDK self-sufficient and guarantees identical
+ * behavior in all environments (server and browser).
+ */
+export declare class TextDecoder {
+    /**
+     * The encoding supported by this polyfill, which is always "utf-8".
+     * This read-only property is required for full API compliance with TypeScript's built-in types.
+     */
+    readonly encoding = "utf-8";
+    /**
+     * The `fatal` option is not supported by this polyfill but is required for API compliance.
+     */
+    readonly fatal = false;
+    /**
+     * The `ignoreBOM` option is not supported by this polyfill but is required for API compliance.
+     */
+    readonly ignoreBOM = false;
+    /**
+     * Decodes a Uint8Array containing UTF-8 bytes into a JavaScript string.
+     * @param octets The byte array to decode.
+     * @returns The decoded string.
+     */
+    decode(octets: Uint8Array): string;
+}
+export declare class TextEncoder {
+    /**
+     * The encoding supported by this polyfill, which is always "utf-8".
+     * This read-only property is required for full API compliance with TypeScript's built-in types.
+     */
+    readonly encoding = "utf-8";
+    /**
+     * Encodes a JavaScript string into a UTF-8 encoded Uint8Array.
+     * @param str The string to encode.
+     * @returns A Uint8Array containing the UTF-8 bytes.
+     */
+    encode(str: string): Uint8Array;
+    /**
+     * An implementation of the `encodeInto` method for API compliance.
+     * Our SDK does not use this performance-optimization method, so this is
+     * a minimal, correct stub that performs a simple encode and copy.
+     */
+    encodeInto(str: string, destination: Uint8Array): {
+        read: number;
+        written: number;
+    };
+}

package/dist/internal/polyfills.js

@@ -0,0 +1,150 @@
+/**
+ * @file Provides robust, production-quality polyfills for TextEncoder and TextDecoder.
+ * The logic is adapted from a public-domain UTF-8 implementation to ensure correctness
+ * and full Unicode support, including surrogate pairs.
+ *
+ * The Javy runtime has partial/non-compliant support for these APIs, so providing
+ * our own implementation makes the SDK self-sufficient and guarantees identical
+ * behavior in all environments (server and browser).
+ */
+// To the extent possible under law, the author(s) have dedicated all copyright and related
+// and neighboring rights to this software to the public domain worldwide. This software
+// is distributed without any warranty.
+// You should have received a copy of the CC0 Public Domain Dedication along with this
+// software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
+export class TextDecoder {
+    constructor() {
+        /**
+         * The encoding supported by this polyfill, which is always "utf-8".
+         * This read-only property is required for full API compliance with TypeScript's built-in types.
+         */
+        this.encoding = 'utf-8';
+        /**
+         * The `fatal` option is not supported by this polyfill but is required for API compliance.
+         */
+        this.fatal = false;
+        /**
+         * The `ignoreBOM` option is not supported by this polyfill but is required for API compliance.
+         */
+        this.ignoreBOM = false;
+    }
+    /**
+     * Decodes a Uint8Array containing UTF-8 bytes into a JavaScript string.
+     * @param octets The byte array to decode.
+     * @returns The decoded string.
+     */
+    decode(octets) {
+        let string = '';
+        let i = 0;
+        while (i < octets.length) {
+            let octet = octets[i];
+            let bytesNeeded = 0;
+            let codePoint = 0;
+            if (octet <= 0x7F) {
+                bytesNeeded = 0;
+                codePoint = octet & 0xFF;
+            }
+            else if (octet <= 0xDF) {
+                bytesNeeded = 1;
+                codePoint = octet & 0x1F;
+            }
+            else if (octet <= 0xEF) {
+                bytesNeeded = 2;
+                codePoint = octet & 0x0F;
+            }
+            else if (octet <= 0xF4) {
+                bytesNeeded = 3;
+                codePoint = octet & 0x07;
+            }
+            if (octets.length - i - bytesNeeded > 0) {
+                let k = 0;
+                while (k < bytesNeeded) {
+                    octet = octets[i + k + 1];
+                    codePoint = (codePoint << 6) | (octet & 0x3F);
+                    k += 1;
+                }
+            }
+            else {
+                // In case of a truncated multi-byte sequence, substitute with a replacement character.
+                codePoint = 0xFFFD;
+                bytesNeeded = octets.length - i;
+            }
+            // `String.fromCodePoint` is the modern, correct way to handle code points
+            // that may be outside the BMP.
+            string += String.fromCodePoint(codePoint);
+            i += bytesNeeded + 1;
+        }
+        return string;
+    }
+}
+export class TextEncoder {
+    constructor() {
+        /**
+         * The encoding supported by this polyfill, which is always "utf-8".
+         * This read-only property is required for full API compliance with TypeScript's built-in types.
+         */
+        this.encoding = 'utf-8';
+    }
+    /**
+     * Encodes a JavaScript string into a UTF-8 encoded Uint8Array.
+     * @param str The string to encode.
+     * @returns A Uint8Array containing the UTF-8 bytes.
+     */
+    encode(str) {
+        const octets = [];
+        const length = str.length;
+        let i = 0;
+        while (i < length) {
+            // The `codePointAt` method is essential for correctly handling characters
+            // outside the Basic Multilingual Plane (like many emojis).
+            const codePoint = str.codePointAt(i);
+            let c = 0;
+            let bits = 0;
+            if (codePoint <= 0x0000007F) {
+                c = 0;
+                bits = 0x00;
+            }
+            else if (codePoint <= 0x000007FF) {
+                c = 6;
+                bits = 0xC0;
+            }
+            else if (codePoint <= 0x0000FFFF) {
+                c = 12;
+                bits = 0xE0;
+            }
+            else if (codePoint <= 0x001FFFFF) {
+                c = 18;
+                bits = 0xF0;
+            }
+            octets.push(bits | (codePoint >> c));
+            c -= 6;
+            while (c >= 0) {
+                octets.push(0x80 | ((codePoint >> c) & 0x3F));
+                c -= 6;
+            }
+            // Advance by 2 if it was a surrogate pair, otherwise 1.
+            i += codePoint >= 0x10000 ? 2 : 1;
+        }
+        // The native API returns a Uint8Array, so we do the same for compatibility.
+        return new Uint8Array(octets);
+    }
+    /**
+     * An implementation of the `encodeInto` method for API compliance.
+     * Our SDK does not use this performance-optimization method, so this is
+     * a minimal, correct stub that performs a simple encode and copy.
+     */
+    encodeInto(str, destination) {
+        const bytes = this.encode(str);
+        const written = Math.min(bytes.length, destination.length);
+        destination.set(bytes.subarray(0, written));
+        // A true implementation would need to correctly calculate how many source
+        // characters were read to produce the written bytes. For our non-blocking
+        // SDK, this simplified stub is sufficient and safe.
+        let read = str.length;
+        if (bytes.length > destination.length) {
+            // A simplistic reverse-calculation if truncated.
+            read = new TextDecoder().decode(destination).length;
+        }
+        return { read, written };
+    }
+}

package/dist/security.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @file Simple Platform Security SDK
+ *
+ * This module provides the global-style, fluent API for authoring security policies
+ * in a standard JavaScript (`.js`) file. It is designed to be executed by the
+ * platform's "Smart Compiler" (a Record Behavior) to produce a declarative
+ * JSON artifact.
+ */
+export type FilterCondition = Record<string, any>;
+export interface Grant {
+    '*'?: boolean | Rule | Rule[];
+    'aggregate'?: {
+        allow?: {
+            avg?: boolean | string[];
+            count?: boolean;
+            max?: boolean | string[];
+            min?: boolean | string[];
+            sum?: boolean | string[];
+        };
+        allowRawData?: boolean;
+        filter?: Rule | Rule[];
+    };
+    'create'?: boolean | Rule | Rule[];
+    'delete'?: boolean | Rule | Rule[];
+    'edit'?: boolean | Rule | Rule[];
+    'inherits'?: string[];
+    'read'?: boolean | Rule | Rule[];
+}
+export interface GrantsObject {
+    [roleName: string]: Grant;
+}
+export interface LookupConfig {
+    filter?: Record<string, any>;
+    resource: string;
+    select: string;
+}
+/**
+ * The final, declarative JSON artifact for a single policy.
+ * @internal
+ */
+export interface Policy {
+    grants: GrantsObject;
+    resource: string;
+}
+export interface Rule {
+    check?: {
+        condition: FilterCondition;
+        errorMessage: string;
+    };
+    columns?: {
+        except: string[];
+    };
+    filter?: FilterCondition;
+    preset?: Record<string, any>;
+}
+declare global {
+    /**
+     * Logically combines multiple rules with an AND condition.
+     * An array of rules `[rule1, rule2]` is shorthand for `and(rule1, rule2)`.
+     */
+    function and(...rules: Rule[]): {
+        _and: Rule[];
+    };
+    /**
+     * Creates a validation rule for mutations.
+     * If the condition is met, the mutation is allowed. If not, the transaction
+     * is rejected with the provided error message.
+     * @param errorMessage The error message to return if the check fails.
+     * @param condition The filter-style condition object to validate.
+     */
+    function check(errorMessage: string, condition: FilterCondition): Rule;
+    /**
+     * A helper for column-level security that denies access to specific fields.
+     * @param fields A list of field names to hide.
+     */
+    function deny(...fields: string[]): {
+        columns: {
+            except: string[];
+        };
+    };
+    /**
+     * Creates a lookup rule for filtering against an unrelated resource.
+     * This is translated into a subquery by the SQLCompiler.
+     * @param config The lookup configuration.
+     * @example
+     * // Restrict access to projects where the current user is a team member.
+     * const rule = {
+     *   filter: {
+     *     id: {
+     *       _in: lookup({
+     *         resource: 'my_app/table/project_member',
+     *         select: 'project_id',
+     *         filter: { user_id: { _eq: '$user.id' } }
+     *       })
+     *     }
+     *   }
+     * };
+     */
+    function lookup(config: LookupConfig): any;
+    /**
+     * Negates a rule.
+     */
+    function not(rule: Rule): {
+        _not: Rule;
+    };
+    /**
+     * Logically combines multiple rules with an OR condition.
+     */
+    function or(...rules: Rule[]): {
+        _or: Rule[];
+    };
+    /**
+     * Defines a security policy for a specific resource.
+     * @param resourceName The full name of the target resource, following the pattern `app_id/table/resource_name` or `app_id/logic/resource_name`.
+     * @param grantsObject An object defining the permissions for each role.
+     * @example
+     * // Define reusable rule constants for clarity
+     * const when = {
+     *   isOwner: { filter: { creator_id: { _eq: '$user.id' } } },
+     *   isDraft: { filter: { status: { _eq: 'Draft' } } }
+     * };
+     *
+     * const hide = {
+     *   financials: deny('rate', 'commission')
+     * };
+     *
+     * // Define a policy for the 'booking' table in the 'crm' app
+     * policy('crm/table/booking', {
+     *   // Agents can read their own bookings and we hide financial fields.
+     *   agent: {
+     *     read: [when.isOwner, hide.financials],
+     *     create: true, // Can create new bookings
+     *     edit: [when.isOwner, when.isDraft] // Can only edit their own bookings if they are in draft status
+     *   },
+     *
+     *   // Managers have full access to all bookings.
+     *   manager: {
+     *     '*': true // Wildcard for all permissions
+     *   },
+     *
+     *   // Finance users have limited, read-only aggregation rights.
+     *   finance: {
+     *     read: false, // Cannot read individual booking records
+     *     aggregate: {
+     *       allowNodes: false, // Cannot view the raw data rows
+     *       allow: {
+     *         count: true,
+     *         sum: ['amount', 'commission'] // Can only sum these specific numeric fields
+     *       }
+     *     }
+     *   }
+     * });
+     *
+     * // Define a policy for a logic/action resource
+     * policy('crm/logic/send_invoice', {
+     *   // Only managers and agents can execute this action.
+     *   manager: { execute: true },
+     *   agent: { execute: true }
+     * });
+     */
+    function policy(resourceName: string, grantsObject: GrantsObject): void;
+}
+/**
+ * Clears the internal policy array.
+ * Called by the "Smart Compiler" to reset state between executions.
+ * @internal
+ */
+export declare function clearCompiledPolicies(): void;
+/**
+ * Retrieves the array of compiled policies.
+ * Called by the "Smart Compiler" Record Behavior after executing the manifest.
+ * @internal
+ */
+export declare function getCompiledPolicies(): Policy[];

package/dist/security.js

@@ -0,0 +1,60 @@
+/**
+ * @file Simple Platform Security SDK
+ *
+ * This module provides the global-style, fluent API for authoring security policies
+ * in a standard JavaScript (`.js`) file. It is designed to be executed by the
+ * platform's "Smart Compiler" (a Record Behavior) to produce a declarative
+ * JSON artifact.
+ */
+// ============================================================================
+// Internal State & Types
+// ============================================================================
+/**
+ * A module-level array that will hold the compiled policies after the user's
+ * security manifest script has been executed.
+ * @internal
+ */
+const _compiledPolicies = [];
+globalThis.policy = (resourceName, grantsObject) => {
+    _compiledPolicies.push({
+        grants: grantsObject,
+        resource: resourceName,
+    });
+};
+globalThis.lookup = (config) => {
+    // This function simply returns a structured object that the compiler can identify.
+    return { $$isLookup: true, ...config };
+};
+globalThis.and = (...rules) => ({ _and: rules });
+globalThis.or = (...rules) => ({ _or: rules });
+globalThis.not = (rule) => ({ _not: rule });
+globalThis.deny = (...fields) => {
+    return { columns: { except: fields.flat() } };
+};
+globalThis.check = (errorMessage, condition) => {
+    return {
+        check: {
+            condition,
+            errorMessage,
+        },
+    };
+};
+// ============================================================================
+// Internal Helpers for the Compiler
+// ============================================================================
+/**
+ * Clears the internal policy array.
+ * Called by the "Smart Compiler" to reset state between executions.
+ * @internal
+ */
+export function clearCompiledPolicies() {
+    _compiledPolicies.length = 0;
+}
+/**
+ * Retrieves the array of compiled policies.
+ * Called by the "Smart Compiler" Record Behavior after executing the manifest.
+ * @internal
+ */
+export function getCompiledPolicies() {
+    return _compiledPolicies;
+}