@arcote.tech/arc 0.3.5 → 0.3.6

package/dist/adapters/command-wire.d.ts

@@ -4,6 +4,7 @@
  * Extends Wire to provide command-specific functionality:
  * - Execute commands remotely on the server
  * - Handle command request/response serialization
+ * - Automatic FormData handling for file uploads
  */
 import { Wire } from "./wire";
 export declare class CommandWire extends Wire {
@@ -16,6 +17,15 @@ export declare class CommandWire extends Wire {
      * @returns Command result from server
      */
     executeCommand(name: string, params: any): Promise<any>;
+    /**
+     * Check if object contains any File instances (recursively)
+     */
+    private containsFile;
+    /**
+     * Convert params object to FormData for file uploads
+     * Files are appended directly, other values are JSON-stringified
+     */
+    private toFormData;
     /**
      * Register a command handler on the server side
      * Called during init() for server environment

package/dist/adapters/event-wire.d.ts

@@ -23,6 +23,7 @@ export interface ReceivedEvent {
 type EventWireState = "disconnected" | "connecting" | "connected";
 export declare class EventWire {
     private readonly baseUrl;
+    private instanceId;
     private ws;
     private state;
     private token;

package/dist/context-element/tree/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tree module
+ *
+ * Provides hierarchical data structures with multiple node types
+ */
+export * from "./tree";
+export * from "./tree-context";
+export * from "./tree-data";
+//# sourceMappingURL=index.d.ts.map

package/dist/context-element/tree/tree-context.d.ts

@@ -0,0 +1,98 @@
+import type { ArcObjectAny } from "../../elements/object";
+import type { $type } from "../../utils/types/get-type";
+import type { ArcTreeData } from "./tree-data";
+/**
+ * Tree node as returned from queries
+ * Includes node data plus tree metadata
+ */
+export interface TreeNode<NodeTypes extends Record<string, ArcObjectAny> = Record<string, ArcObjectAny>, T extends keyof NodeTypes = keyof NodeTypes> {
+    _id: string;
+    type: T;
+    parentId: string | null;
+    order: number;
+    treeId: string;
+    data: T extends keyof NodeTypes ? $type<NodeTypes[T]> : never;
+}
+/**
+ * Tree edge record
+ */
+export interface TreeEdge {
+    _id: string;
+    childId: string;
+    parentId: string | null;
+    childType: string;
+    order: number;
+    treeId: string;
+}
+/**
+ * Options for tree find queries
+ */
+export interface TreeFindOptions<NodeTypes extends Record<string, ArcObjectAny>> {
+    /** Filter by specific node types */
+    types?: (keyof NodeTypes)[];
+    /** Filter by parent ID (null for root nodes) */
+    parentId?: string | null;
+    /** Filter by tree ID (for multi-tenant) */
+    treeId?: string;
+    /** Sort order */
+    orderBy?: {
+        order: "asc" | "desc";
+    };
+    /** Limit results */
+    limit?: number;
+    /** Recursive depth (for findDescendants) */
+    depth?: number;
+}
+/**
+ * Query context for reading tree data
+ */
+export interface TreeQueryContext<Data extends ArcTreeData> {
+    /** Find nodes with optional filtering */
+    find(options?: TreeFindOptions<Data["nodeTypes"]>): Promise<TreeNode<Data["nodeTypes"]>[]>;
+    /** Find single node by ID */
+    findOne(id: string): Promise<TreeNode<Data["nodeTypes"]> | undefined>;
+    /** Find direct children of a node */
+    findChildren(parentId: string | null, options?: {
+        types?: (keyof Data["nodeTypes"])[];
+        treeId?: string;
+    }): Promise<TreeNode<Data["nodeTypes"]>[]>;
+    /** Find ancestors (path to root) */
+    findAncestors(nodeId: string): Promise<TreeNode<Data["nodeTypes"]>[]>;
+    /** Find descendants recursively */
+    findDescendants(nodeId: string, depth?: number): Promise<TreeNode<Data["nodeTypes"]>[]>;
+}
+/**
+ * Mutation context for modifying tree data
+ */
+export interface TreeMutationContext<Data extends ArcTreeData> {
+    /** Create a new node */
+    create<T extends keyof Data["nodeTypes"]>(type: T, data: $type<Data["nodeTypes"][T]>, options?: {
+        parentId?: string | null;
+        order?: number;
+        treeId?: string;
+    }): Promise<string>;
+    /** Update node data */
+    update<T extends keyof Data["nodeTypes"]>(id: string, data: Partial<$type<Data["nodeTypes"][T]>>): Promise<void>;
+    /** Delete node (with cascade) */
+    delete(id: string): Promise<void>;
+    /** Move node to new parent/position */
+    move(id: string, options: {
+        parentId?: string | null;
+        order?: number;
+    }): Promise<void>;
+}
+/**
+ * Serialized tree format for export/import
+ */
+export interface SerializedTree<Data extends ArcTreeData> {
+    name: string;
+    treeId: string;
+    nodes: {
+        [K in keyof Data["nodeTypes"]]?: Array<{
+            _id: string;
+            data: $type<Data["nodeTypes"][K]>;
+        }>;
+    };
+    edges: TreeEdge[];
+}
+//# sourceMappingURL=tree-context.d.ts.map

package/dist/context-element/tree/tree-data.d.ts

@@ -0,0 +1,43 @@
+import type { ArcObjectAny } from "../../elements/object";
+import type { ArcTokenAny } from "../../token/token";
+/**
+ * Protection function for tree access control
+ * Returns read/write conditions based on token params
+ */
+export type TreeProtectionFn<T extends ArcTokenAny> = (params: T extends {
+    params: infer P;
+} ? P : never) => {
+    read?: Record<string, any> | false;
+    write?: Record<string, any> | false;
+} | false;
+/**
+ * Tree protection configuration
+ */
+export interface TreeProtection<T extends ArcTokenAny = ArcTokenAny> {
+    token: T;
+    protectionFn: TreeProtectionFn<T>;
+}
+/**
+ * Node type definition within a tree
+ */
+export interface TreeNodeTypeDefinition<Name extends string = string, Schema extends ArcObjectAny = ArcObjectAny> {
+    name: Name;
+    schema: Schema;
+}
+/**
+ * Data structure for ArcTree configuration
+ * Follows Arc's factory pattern with immutable data
+ */
+export interface ArcTreeData {
+    /** Unique tree name */
+    name: string;
+    /** Optional description for documentation */
+    description?: string;
+    /** Map of node type names to their schemas */
+    nodeTypes: Record<string, ArcObjectAny>;
+    /** Token-based protections */
+    protections: TreeProtection[];
+    /** Tree ID field name for multi-tenant support */
+    treeIdField?: string;
+}
+//# sourceMappingURL=tree-data.d.ts.map

package/dist/context-element/tree/tree.d.ts

@@ -0,0 +1,142 @@
+import type { DatabaseStoreSchema } from "../../data-storage/database-store";
+import { ArcObject, type ArcObjectAny, type ArcRawShape } from "../../elements/object";
+import type { ModelAdapters } from "../../model/model-adapters";
+import type { ArcTokenAny } from "../../token/token";
+import type { Merge } from "../../utils";
+import { ArcContextElement } from "../context-element";
+import type { SerializedTree, TreeMutationContext, TreeQueryContext } from "./tree-context";
+import type { ArcTreeData, TreeProtectionFn } from "./tree-data";
+/**
+ * Arc Tree - Hierarchical data structure with multiple node types
+ *
+ * Trees enable defining hierarchical data where each node type has its own
+ * dedicated view/table. The tree provides a unified query interface that
+ * joins these views based on parent-child relationships.
+ *
+ * @example
+ * ```typescript
+ * const contentTree = tree("contentTree")
+ *   .nodeType("texts", { text: string() })
+ *   .nodeType("brollIdeas", { idea: string() })
+ *   .nodeType("graphicIdeas", { idea: string() });
+ * ```
+ */
+export declare class ArcTree<const Data extends ArcTreeData> extends ArcContextElement<Data["name"]> {
+    private readonly data;
+    constructor(data: Data);
+    /**
+     * Get tree name
+     */
+    get treeName(): Data["name"];
+    /**
+     * Get node types configuration
+     */
+    get nodeTypes(): Data["nodeTypes"];
+    /**
+     * Set tree description for documentation
+     */
+    description<const Desc extends string>(description: Desc): ArcTree<Merge<Data, {
+        description: Desc;
+    }>>;
+    /**
+     * Define a node type with its schema
+     * Each node type gets its own dedicated view/table
+     *
+     * @param typeName - Unique name for this node type within the tree
+     * @param schema - Schema defining the node's data fields
+     */
+    nodeType<TypeName extends string, Schema extends ArcRawShape | ArcObjectAny>(typeName: TypeName, schema: Schema): ArcTree<Merge<Data, {
+        nodeTypes: Data["nodeTypes"] & { [K in TypeName]: ArcObject<ArcRawShape, [{
+            name: "type";
+            validator: (value: any) => false | {
+                current: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
+                expected: "object";
+            };
+        }, {
+            name: "schema";
+            validator: (value: any) => false | {
+                [x: string]: unknown;
+            };
+        }]> | (Schema & ArcObject<any, any>); };
+    }>>;
+    /**
+     * Add token-based protection to this tree
+     * Defines read/write access conditions based on token params
+     */
+    protectBy<T extends ArcTokenAny>(token: T, protectionFn: TreeProtectionFn<T>): ArcTree<Data>;
+    /**
+     * Check if tree has protections
+     */
+    get hasProtections(): boolean;
+    /**
+     * Get all protection configurations
+     */
+    get protections(): import("./tree-data").TreeProtection<ArcTokenAny>[];
+    /**
+     * Generate all context elements (events, views) for this tree
+     * These should be registered in the Arc context
+     */
+    getElements(): ArcContextElement<any>[];
+    /**
+     * Generate query context for this tree
+     * Provides read access to tree data
+     */
+    queryContext(adapters: ModelAdapters): TreeQueryContext<Data>;
+    /**
+     * Generate mutation context for this tree
+     * Provides write access to tree data
+     */
+    mutateContext(adapters: ModelAdapters): TreeMutationContext<Data>;
+    /**
+     * Generate database store schema for this tree
+     * Returns schemas for all node type views + edges view
+     */
+    databaseStoreSchema(): DatabaseStoreSchema;
+    /**
+     * Serialize tree data to JSON format
+     * Exports nodes grouped by type and edges array
+     *
+     * @param adapters - Model adapters for data access
+     * @param treeId - Tree ID to serialize (defaults to "default")
+     */
+    serialize(adapters: ModelAdapters, treeId?: string): Promise<SerializedTree<Data>>;
+    /**
+     * Serialize a subtree starting from a specific node
+     * Includes only the specified node and its descendants
+     *
+     * @param adapters - Model adapters for data access
+     * @param nodeId - Root node ID of the subtree
+     */
+    serializeSubtree(adapters: ModelAdapters, nodeId: string): Promise<SerializedTree<Data>>;
+    /**
+     * Deserialize tree data from JSON format
+     * Validates node data against schemas and reconstructs relationships
+     *
+     * @param adapters - Model adapters for data access
+     * @param serialized - Serialized tree data
+     */
+    deserialize(adapters: ModelAdapters, serialized: SerializedTree<Data>): Promise<void>;
+}
+/**
+ * Create a new tree with the given name
+ *
+ * @param name - Unique tree name
+ * @returns New tree instance ready for configuration
+ *
+ * @example
+ * ```typescript
+ * const contentTree = tree("contentTree")
+ *   .nodeType("texts", { text: string() })
+ *   .nodeType("brollIdeas", { idea: string() });
+ * ```
+ */
+export declare function tree<const Name extends string>(name: Name): ArcTree<{
+    name: Name;
+    nodeTypes: {};
+    protections: [];
+}>;
+/**
+ * Type alias for any tree (used in collections)
+ */
+export type ArcTreeAny = ArcTree<any>;
+//# sourceMappingURL=tree.d.ts.map

package/dist/index.js

@@ -84,9 +84,19 @@ class CommandWire extends Wire {
     super(baseUrl);
   }
   async executeCommand(name, params) {
+    const hasFile = this.containsFile(params);
+    let body;
+    let headers;
+    if (hasFile) {
+      body = this.toFormData(params);
+    } else {
+      body = JSON.stringify(params);
+      headers = { "Content-Type": "application/json" };
+    }
     const response = await this.fetch(`/command/${name}`, {
       method: "POST",
-      body: JSON.stringify(params)
+      body,
+      headers
     });
     if (!response.ok) {
       const errorText = await response.text();
@@ -94,10 +104,35 @@ class CommandWire extends Wire {
     }
     return await response.json();
   }
+  containsFile(obj) {
+    if (obj instanceof File || obj instanceof Blob)
+      return true;
+    if (obj === null || typeof obj !== "object")
+      return false;
+    if (Array.isArray(obj))
+      return obj.some((v) => this.containsFile(v));
+    return Object.values(obj).some((v) => this.containsFile(v));
+  }
+  toFormData(params) {
+    const formData = new FormData;
+    for (const [key, value] of Object.entries(params)) {
+      if (value instanceof File) {
+        formData.append(key, value, value.name);
+      } else if (value instanceof Blob) {
+        formData.append(key, value);
+      } else {
+        formData.append(key, JSON.stringify(value));
+      }
+    }
+    return formData;
+  }
 }
 // src/adapters/event-wire.ts
+var eventWireInstanceCounter = 0;
+
 class EventWire {
   baseUrl;
+  instanceId;
   ws = null;
   state = "disconnected";
   token = null;
@@ -109,6 +144,7 @@ class EventWire {
   syncRequested = false;
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
+    this.instanceId = ++eventWireInstanceCounter;
   }
   setAuthToken(token) {
     this.token = token;
@@ -127,16 +163,26 @@ class EventWire {
     if (this.state !== "disconnected")
       return;
     this.state = "connecting";
-    const wsUrl = this.baseUrl.replace(/^http/, "ws");
+    let wsUrl;
+    if (this.baseUrl.startsWith("http://") || this.baseUrl.startsWith("https://")) {
+      wsUrl = this.baseUrl.replace(/^http/, "ws");
+    } else {
+      const protocol = typeof window !== "undefined" && window.location.protocol === "https:" ? "wss:" : "ws:";
+      const host = typeof window !== "undefined" ? window.location.host : "localhost";
+      wsUrl = `${protocol}//${host}${this.baseUrl}`;
+    }
     const tokenParam = this.token ? `?token=${this.token}` : "";
     const url = `${wsUrl}/ws${tokenParam}`;
     try {
       this.ws = new WebSocket(url);
       this.ws.onopen = () => {
-        this.state = "connected";
-        console.log(`EventWire connected`);
-        this.requestSync();
-        this.flushPendingEvents();
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+          this.state = "connected";
+          this.requestSync();
+          this.flushPendingEvents();
+        } else {
+          console.log(`[EventWire] onopen called but ws is not OPEN, readyState:`, this.ws?.readyState);
+        }
       };
       this.ws.onmessage = (event) => {
         try {
@@ -146,7 +192,7 @@ class EventWire {
           console.error("EventWire: Failed to parse message", err);
         }
       };
-      this.ws.onclose = () => {
+      this.ws.onclose = (event) => {
         this.state = "disconnected";
         this.ws = null;
         console.log("EventWire disconnected");
@@ -154,9 +200,14 @@ class EventWire {
       };
       this.ws.onerror = (err) => {
         console.error("EventWire error:", err);
+        if (this.state === "connecting") {
+          this.state = "disconnected";
+          this.ws = null;
+        }
       };
     } catch (err) {
       this.state = "disconnected";
+      this.ws = null;
       console.error("EventWire: Failed to connect", err);
       this.scheduleReconnect();
     }
@@ -174,19 +225,28 @@ class EventWire {
     this.syncRequested = false;
   }
   syncEvents(events) {
-    if (this.state !== "connected" || !this.ws) {
+    const isActuallyConnected = this.ws && this.ws.readyState === WebSocket.OPEN;
+    if (!isActuallyConnected) {
+      if (this.state === "connected" && !this.ws) {
+        this.state = "disconnected";
+      }
       this.pendingEvents.push(...events);
+      if (this.state === "disconnected") {
+        this.connect();
+      }
       return;
     }
-    this.ws.send(JSON.stringify({
-      type: "sync-events",
-      events: events.map((e) => ({
-        localId: e.localId,
-        type: e.type,
-        payload: e.payload,
-        createdAt: e.createdAt
-      }))
-    }));
+    if (this.ws) {
+      this.ws.send(JSON.stringify({
+        type: "sync-events",
+        events: events.map((e) => ({
+          localId: e.localId,
+          type: e.type,
+          payload: e.payload,
+          createdAt: e.createdAt
+        }))
+      }));
+    }
   }
   onEvent(callback) {
     this.onEventCallback = callback;

package/dist/observability/index.d.ts

@@ -0,0 +1,4 @@
+export { ArcTelemetry, type ObservabilityMode, type TelemetryConfig, } from "./telemetry";
+export { initBrowserTelemetry } from "./telemetry-browser";
+export { initServerTelemetry } from "./telemetry-server";
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/telemetry-browser.d.ts

@@ -0,0 +1,6 @@
+import { ArcTelemetry, type TelemetryConfig } from "./telemetry";
+/**
+ * Initialize OpenTelemetry for browser environment
+ */
+export declare function initBrowserTelemetry(config: TelemetryConfig): ArcTelemetry;
+//# sourceMappingURL=telemetry-browser.d.ts.map

package/dist/observability/telemetry-server.d.ts

@@ -0,0 +1,6 @@
+import { ArcTelemetry, type TelemetryConfig } from "./telemetry";
+/**
+ * Initialize OpenTelemetry for Node.js/Bun server environment
+ */
+export declare function initServerTelemetry(config: TelemetryConfig): ArcTelemetry;
+//# sourceMappingURL=telemetry-server.d.ts.map

package/dist/observability/telemetry.d.ts

@@ -0,0 +1,51 @@
+import { type Span } from "@opentelemetry/api";
+export type ObservabilityMode = "development" | "production" | "disabled";
+export interface TelemetryConfig {
+    serviceName: string;
+    environment: "client" | "server";
+    endpoint?: string;
+    enabled?: boolean;
+    sampleRate?: number;
+    mode?: ObservabilityMode;
+    includePayloads?: boolean;
+    debug?: boolean;
+}
+/**
+ * Arc Telemetry - Wrapper around OpenTelemetry for Arc Framework
+ *
+ * Provides simplified API for tracing commands, events, and views
+ */
+export declare class ArcTelemetry {
+    private tracer;
+    readonly config: TelemetryConfig;
+    constructor(config: TelemetryConfig);
+    /**
+     * Set the tracer instance (called by init functions)
+     */
+    setTracer(tracer: any): void;
+    /**
+     * Start a span with automatic error handling
+     */
+    startSpan<T>(name: string, fn: (span: Span) => Promise<T>, attributes?: Record<string, any>): Promise<T>;
+    /**
+     * Get current active span
+     */
+    getCurrentSpan(): Span | undefined;
+    /**
+     * Add attributes to current span
+     */
+    addAttributes(attributes: Record<string, any>): void;
+    /**
+     * Create a child span (must be manually ended)
+     */
+    createChildSpan(name: string, attributes?: Record<string, any>): Span | undefined;
+    /**
+     * Serialize value for span attributes (handles objects, arrays, etc)
+     */
+    private serializeValue;
+    /**
+     * Check if payloads should be included based on mode
+     */
+    shouldIncludePayloads(): boolean;
+}
+//# sourceMappingURL=telemetry.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc",
   "type": "module",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "private": false,
   "author": "Przemysław Krasiński [arcote.tech]",
   "description": "Arc framework core rewrite with improved event emission and type safety",