toiljs 0.0.1

package/presets/eslint.js

@@ -0,0 +1,77 @@
+// toiljs shared ESLint flat config — opinionated, strict, React-aware.
+// Use it from your project's eslint.config.js:
+//   import toiljs from 'toiljs/eslint';
+//   export default toiljs;
+import eslintReact from '@eslint-react/eslint-plugin';
+import eslint from '@eslint/js';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+
+import noUint8ArrayToString from './no-uint8array-tostring.js';
+
+export default tseslint.config(
+    // Build output + the toil-generated working dir are not hand-written source.
+    { ignores: ['dist', 'build', '.toil', 'node_modules'] },
+    {
+        extends: [
+            eslint.configs.recommended,
+            ...tseslint.configs.recommended,
+            ...tseslint.configs.strictTypeChecked,
+        ],
+        files: ['**/*.{ts,tsx}'],
+        languageOptions: {
+            ecmaVersion: 2023,
+            // No tsconfigRootDir: projectService discovers the consumer's tsconfig from cwd.
+            parserOptions: {
+                projectService: true,
+            },
+        },
+        plugins: {
+            'react-hooks': reactHooks,
+            'react-refresh': reactRefresh,
+            '@eslint-react': eslintReact,
+            custom: noUint8ArrayToString,
+        },
+        rules: {
+            ...reactHooks.configs.recommended.rules,
+            'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+            'no-undef': 'off',
+            '@typescript-eslint/no-unused-vars': 'off',
+            'no-empty': 'off',
+            '@typescript-eslint/restrict-template-expressions': 'off',
+            '@typescript-eslint/only-throw-error': 'off',
+            '@typescript-eslint/no-unnecessary-condition': 'off',
+            '@typescript-eslint/unbound-method': 'warn',
+            '@typescript-eslint/no-confusing-void-expression': 'off',
+            '@typescript-eslint/no-extraneous-class': 'off',
+            'no-async-promise-executor': 'off',
+            '@typescript-eslint/no-misused-promises': 'off',
+            '@typescript-eslint/no-unnecessary-type-parameters': 'off',
+            '@typescript-eslint/no-duplicate-enum-values': 'off',
+            'prefer-spread': 'off',
+            '@typescript-eslint/no-empty-object-type': 'off',
+            '@typescript-eslint/no-floating-promises': 'off',
+            '@typescript-eslint/ban-ts-comment': 'off',
+            'no-constant-binary-expression': 'off',
+            'no-useless-assignment': 'off',
+            '@typescript-eslint/no-unsafe-assignment': 'off',
+            '@typescript-eslint/no-unsafe-call': 'off',
+            '@typescript-eslint/no-unsafe-member-access': 'off',
+            '@typescript-eslint/no-unsafe-argument': 'off',
+            '@typescript-eslint/no-unnecessary-type-conversion': 'warn',
+            'react-hooks/set-state-in-effect': 'warn',
+            'custom/no-uint8array-tostring': 'error',
+            'padding-line-between-statements': [
+                'error',
+                { blankLine: 'always', prev: 'block-like', next: '*' },
+            ],
+            '@typescript-eslint/no-deprecated': 'off',
+            '@typescript-eslint/no-unnecessary-type-arguments': 'off',
+        },
+    },
+    {
+        files: ['**/*.js'],
+        ...tseslint.configs.disableTypeChecked,
+    },
+);

package/presets/no-uint8array-tostring.js

@@ -0,0 +1,201 @@
+// ESLint rule: disallow `.toString()` on Uint8Array (and branded byte types), which returns
+// comma-separated decimals instead of hex. Ported to plain JS from the typed source so the
+// shareable preset can load it at runtime without a TypeScript loader.
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils';
+import { SyntaxKind } from 'typescript';
+
+function isUint8ArrayType(type, checker) {
+    const symbol = type.getSymbol();
+    if (symbol?.getName() === 'Uint8Array') {
+        return true;
+    }
+
+    const baseTypes = type.getBaseTypes?.();
+    if (baseTypes) {
+        for (const baseType of baseTypes) {
+            if (isUint8ArrayType(baseType, checker)) {
+                return true;
+            }
+        }
+    }
+
+    if (type.isIntersection()) {
+        for (const subType of type.types) {
+            if (isUint8ArrayType(subType, checker)) {
+                return true;
+            }
+        }
+    }
+
+    if (type.isUnion()) {
+        return (
+            type.types.length > 0 &&
+            type.types.every((subType) => isUint8ArrayType(subType, checker))
+        );
+    }
+
+    const constraint = type.getConstraint?.();
+    if (constraint && isUint8ArrayType(constraint, checker)) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Types whose toString() is the dangerous default behavior we want to catch.
+ * If toString is declared on any type NOT in this set, it has been
+ * intentionally overridden and we should leave it alone.
+ */
+const DEFAULT_TOSTRING_OWNERS = new Set([
+    'Object',
+    'Uint8Array',
+    'Int8Array',
+    'Uint8ClampedArray',
+    'Int16Array',
+    'Uint16Array',
+    'Int32Array',
+    'Uint32Array',
+    'Float32Array',
+    'Float64Array',
+    'BigInt64Array',
+    'BigUint64Array',
+]);
+
+/**
+ * Given a declaration node, walk up the AST parents to find the enclosing
+ * class or interface name. More reliable than checker.getTypeAtLocation(decl.parent),
+ * which can return odd results for .d.ts files.
+ */
+function getEnclosingClassName(decl) {
+    let current = decl.parent;
+    while (current) {
+        if (
+            current.kind === SyntaxKind.ClassDeclaration ||
+            current.kind === SyntaxKind.ClassExpression ||
+            current.kind === SyntaxKind.InterfaceDeclaration
+        ) {
+            if (current.name) {
+                return current.name.text;
+            }
+        }
+
+        current = current.parent;
+    }
+
+    return undefined;
+}
+
+/**
+ * Checks whether the resolved toString() on this type is a custom override
+ * rather than the default Uint8Array/Object prototype version.
+ */
+function hasCustomToString(type, checker) {
+    const toStringSymbol = type.getProperty('toString');
+    if (!toStringSymbol) {
+        return false;
+    }
+
+    const declarations = toStringSymbol.getDeclarations();
+    if (!declarations || declarations.length === 0) {
+        return false;
+    }
+
+    for (const decl of declarations) {
+        const ownerName = getEnclosingClassName(decl);
+        if (ownerName && !DEFAULT_TOSTRING_OWNERS.has(ownerName)) {
+            return true;
+        }
+    }
+
+    // Fallback: also check the apparent type, which can differ for branded
+    // types or type aliases that wrap a class.
+    const apparentType = checker.getApparentType(type);
+    if (apparentType !== type) {
+        const apparentToString = apparentType.getProperty('toString');
+        if (apparentToString && apparentToString !== toStringSymbol) {
+            const apparentDecls = apparentToString.getDeclarations();
+            if (apparentDecls) {
+                for (const decl of apparentDecls) {
+                    const ownerName = getEnclosingClassName(decl);
+                    if (ownerName && !DEFAULT_TOSTRING_OWNERS.has(ownerName)) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+
+    return false;
+}
+
+const createRule = ESLintUtils.RuleCreator(
+    (name) => `https://github.com/dacely-cloud/toiljs/tree/main/presets#${name}`,
+);
+
+const rule = createRule({
+    name: 'no-uint8array-tostring',
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Disallow .toString() on Uint8Array and branded types (Script, Bytes32, etc.) which produces comma-separated decimals instead of hex',
+        },
+        messages: {
+            noUint8ArrayToString:
+                '{{typeName}}.toString() returns comma-separated decimals (e.g. "0,32,70,107"), not a hex string. ' +
+                'Use Buffer.from(arr).toString("hex") or toHex() instead.',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        const services = ESLintUtils.getParserServices(context);
+        const checker = services.program.getTypeChecker();
+
+        return {
+            CallExpression(node) {
+                if (
+                    node.callee.type !== AST_NODE_TYPES.MemberExpression ||
+                    node.callee.property.type !== AST_NODE_TYPES.Identifier ||
+                    node.callee.property.name !== 'toString' ||
+                    node.arguments.length > 0
+                ) {
+                    return;
+                }
+
+                const objectNode = node.callee.object;
+                const tsNode = services.esTreeNodeToTSNodeMap.get(objectNode);
+                const type = checker.getTypeAtLocation(tsNode);
+
+                if (!isUint8ArrayType(type, checker)) {
+                    return;
+                }
+
+                if (hasCustomToString(type, checker)) {
+                    return;
+                }
+
+                const typeName = checker.typeToString(type);
+                context.report({
+                    node,
+                    messageId: 'noUint8ArrayToString',
+                    data: { typeName },
+                });
+            },
+        };
+    },
+});
+
+const plugin = {
+    meta: {
+        name: 'eslint-plugin-no-uint8array-tostring',
+        version: '1.0.0',
+    },
+    rules: {
+        'no-uint8array-tostring': rule,
+    },
+};
+
+export default plugin;
+export { rule };

package/presets/prettier.json

@@ -0,0 +1,11 @@
+{
+    "printWidth": 120,
+    "tabWidth": 4,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "none",
+    "bracketSpacing": true,
+    "bracketSameLine": true,
+    "arrowParens": "always"
+}

package/presets/tsconfig.json

@@ -0,0 +1,37 @@
+// toiljs shared client tsconfig — opinionated, strict.
+// Extend it from your project: { "extends": "toiljs/tsconfig", "include": ["client", ".toil"] }
+{
+    "compilerOptions": {
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "strictBindCallApply": true,
+        "strictPropertyInitialization": true,
+        "noImplicitThis": true,
+        "useUnknownInCatchVariables": true,
+        "alwaysStrict": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "exactOptionalPropertyTypes": false,
+        "noImplicitReturns": false,
+        "noFallthroughCasesInSwitch": true,
+        "noUncheckedIndexedAccess": false,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": false,
+        "module": "ES2020",
+        "target": "ES2020",
+        "moduleResolution": "Bundler",
+        "jsx": "react-jsx",
+        "lib": ["ESNext", "DOM", "DOM.Iterable", "DOM.AsyncIterable"],
+        "isolatedModules": true,
+        "verbatimModuleSyntax": false,
+        "allowImportingTsExtensions": true,
+        "esModuleInterop": true,
+        "resolveJsonModule": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "moduleDetection": "force",
+        "noEmit": true
+    }
+}

package/src/backend/index.ts

@@ -0,0 +1,167 @@
+/**
+ * toiljs backend — the self-host / dev server, built on @btc-vision/hyper-express (uWebSockets.js)
+ * for very high throughput. It serves the built client (static assets + SPA fallback) and exposes
+ * a WebSocket channel for realtime / live updates.
+ *
+ * This is the Node "server" that hosts the app on a local machine; it is distinct from the
+ * AssemblyScript WASM target in `src/server`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+    Server,
+    type MiddlewareNext,
+    type Request,
+    type Response,
+    type Websocket,
+} from '@btc-vision/hyper-express';
+
+const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8; // 8 MB
+const MAX_BODY_BUFFER = 1024 * 32; // 32 KB
+const HTTP_IDLE_TIMEOUT = 60; // seconds
+const HTTP_RESPONSE_TIMEOUT = 120; // seconds
+
+const WS_MAX_PAYLOAD_LENGTH = 1024 * 1024; // 1 MB
+const WS_IDLE_TIMEOUT = 120; // seconds
+const WS_MAX_BACKPRESSURE = 1024 * 1024 * 2; // 2 MB
+
+const CORS_METHODS = 'GET, POST, OPTIONS, PUT, PATCH, DELETE';
+const CORS_HEADERS = 'X-Requested-With, content-type';
+
+/** Options for {@link startBackend}. */
+export interface BackendOptions {
+    /** Directory to serve (the built client `outDir`, e.g. `dist`). */
+    readonly root: string;
+    /** Listening port. Default `3000`. */
+    readonly port?: number;
+    /** Bind host. Default `0.0.0.0`. */
+    readonly host?: string;
+    /** WebSocket channel path. Default `/_toil`. */
+    readonly wsPath?: string;
+    /** Send permissive CORS headers + handle preflight. Default `true`. */
+    readonly cors?: boolean;
+    /** Max request body length in bytes. Default 8 MB. */
+    readonly maxBodyLength?: number;
+}
+
+/** A running backend instance. */
+export interface RunningBackend {
+    readonly port: number;
+    readonly host: string;
+    readonly wsPath: string;
+    /** Sends a message to every connected WebSocket client. */
+    broadcast(message: string): void;
+    /** Number of currently-connected WebSocket clients. */
+    clientCount(): number;
+    /** Gracefully shuts the server down. */
+    close(): Promise<void>;
+}
+
+/** Resolves a request path to a file inside `root`, guarding against path traversal. */
+function resolveStaticFile(root: string, requestPath: string): string | null {
+    const decoded = decodeURIComponent(requestPath);
+    const resolved = path.join(root, decoded);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) return null; // traversal
+    if (decoded === '/' || decoded === '') return null; // defer to SPA fallback
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved;
+    return null;
+}
+
+/**
+ * Starts the hyper-express server serving `root` with an SPA fallback to `index.html`,
+ * plus a WebSocket channel at `wsPath`. Resolves once the server is listening.
+ */
+export async function startBackend(options: BackendOptions): Promise<RunningBackend> {
+    const port = options.port ?? 3000;
+    const host = options.host ?? '0.0.0.0';
+    const wsPath = options.wsPath ?? '/_toil';
+    const cors = options.cors ?? true;
+    const root = path.resolve(options.root);
+    const indexHtml = path.join(root, 'index.html');
+
+    const app = new Server({
+        max_body_length: options.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH,
+        max_body_buffer: MAX_BODY_BUFFER,
+        fast_abort: true,
+        idle_timeout: HTTP_IDLE_TIMEOUT,
+        response_timeout: HTTP_RESPONSE_TIMEOUT,
+    });
+
+    const clients = new Set<Websocket>();
+
+    // Never let an unhandled error leak a stack trace; write a safe response if the socket is live.
+    app.set_error_handler((_request: Request, response: Response, _error: Error) => {
+        if (response.completed) return;
+        response.atomic(() => {
+            response.status(500).json({ error: 'Internal server error.' });
+        });
+    });
+
+    // CORS + hide the underlying server header.
+    if (cors) {
+        app.use((request: Request, response: Response, next: MiddlewareNext) => {
+            if (request.method !== 'OPTIONS') {
+                response.setHeader('Access-Control-Allow-Origin', '*');
+                response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
+                response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
+            }
+            response.removeHeader('uWebSockets');
+            next();
+        });
+        app.options('/*', (_request: Request, response: Response) => {
+            response.setHeader('Access-Control-Allow-Origin', '*');
+            response.setHeader('Access-Control-Allow-Methods', CORS_METHODS);
+            response.setHeader('Access-Control-Allow-Headers', CORS_HEADERS);
+            response.setHeader('Access-Control-Max-Age', '86400');
+            response.status(204).send();
+        });
+    }
+
+    // Realtime WebSocket channel: each client joins, messages are broadcast to all peers.
+    app.ws(
+        wsPath,
+        {
+            message_type: 'String',
+            max_payload_length: WS_MAX_PAYLOAD_LENGTH,
+            idle_timeout: WS_IDLE_TIMEOUT,
+            max_backpressure: WS_MAX_BACKPRESSURE,
+        },
+        (ws) => {
+            clients.add(ws);
+            ws.send(JSON.stringify({ type: 'connected', clients: clients.size }));
+            ws.on('message', (message: string) => {
+                for (const client of clients) client.send(message);
+            });
+            // Backpressure on this socket has drained — broadcast channel has nothing to flush.
+            ws.on('drain', () => {
+                /* no-op */
+            });
+            ws.on('close', () => {
+                clients.delete(ws);
+            });
+        },
+    );
+
+    // Static client with SPA fallback — anything that isn't a real file serves index.html.
+    app.get('/*', (request: Request, response: Response) => {
+        if (response.completed) return;
+        const file = resolveStaticFile(root, request.path);
+        response.sendFile(file ?? indexHtml);
+    });
+
+    await app.listen(port, host);
+
+    return {
+        port,
+        host,
+        wsPath,
+        broadcast: (message: string): void => {
+            for (const client of clients) client.send(message);
+        },
+        clientCount: (): number => clients.size,
+        close: async (): Promise<void> => {
+            await app.shutdown();
+        },
+    };
+}