@dxos/app-graph 0.8.3 → 0.8.4-main.03d5cd7b56

package/src/node.ts

@@ -2,7 +2,30 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type MaybePromise, type MakeOptional } from '@dxos/util';
+import type * as Context from 'effect/Context';
+import type * as Effect from 'effect/Effect';
+
+import { type MakeOptional } from '@dxos/util';
+
+/**
+ * Root node ID.
+ */
+export const RootId = 'root';
+
+/**
+ * Root node type.
+ */
+export const RootType = 'org.dxos.type.graphRoot';
+
+/**
+ * Action node type.
+ */
+export const ActionType = 'org.dxos.type.graphAction';
+
+/**
+ * Action group node type.
+ */
+export const ActionGroupType = 'org.dxos.type.graphActionGroup';
 
 /**
  * Represents a node in the graph.
@@ -46,7 +69,19 @@ export type NodeFilter<TData = any, TProperties extends Record<string, any> = Re
   connectedNode: Node,
 ) => node is Node<TData, TProperties>;
 
-export type Relation = 'outbound' | 'inbound';
+export type RelationDirection = 'outbound' | 'inbound';
+
+export type Relation = Readonly<{
+  kind: string;
+  direction: RelationDirection;
+}>;
+
+export type RelationInput = Relation | string;
+
+export const relation = (kind: string, direction: RelationDirection = 'outbound'): Relation => ({ kind, direction });
+// TODO(wittjosiah): Consider moving these helpers out of the core API.
+export const childRelation = (direction: RelationDirection = 'outbound'): Relation => relation('child', direction);
+export const actionRelation = (direction: RelationDirection = 'outbound'): Relation => relation('action', direction);
 
 export const isGraphNode = (data: unknown): data is Node =>
   data && typeof data === 'object' && 'id' in data && 'properties' in data && data.properties
@@ -61,30 +96,45 @@ export type NodeArg<TData, TProperties extends Record<string, any> = Record<stri
   nodes?: NodeArg<unknown>[];
 
   /** Will automatically add specified edges. */
-  edges?: [string, Relation][];
+  edges?: [string, RelationInput][];
 };
 
 //
 // Actions
 //
 
-export type InvokeParams = {
+export type InvokeProps = {
   /** Node the invoked action is connected to. */
   parent?: Node;
 
+  /** Path from root to the node in the current tree context. */
+  path?: string[];
+
   caller?: string;
 };
 
-export type ActionData = (params?: InvokeParams) => MaybePromise<void>;
+/**
+ * Action data is an Effect-returning function.
+ * The Effect is provided with captured context at execution time.
+ */
+export type ActionData<R = never> = (params?: InvokeProps) => Effect.Effect<any, Error, R>;
+
+/**
+ * Context captured at extension creation time.
+ * Automatically provided to action Effects at execution.
+ */
+export type ActionContext = Context.Context<any>;
 
 export type Action<TProperties extends Record<string, any> = Record<string, any>> = Readonly<
   Omit<Node<ActionData, TProperties>, 'properties'> & {
     properties: Readonly<TProperties>;
+    /** Captured context from extension creation. Provided automatically at action execution. */
+    _actionContext?: ActionContext;
   }
 >;
 
 export const isAction = (data: unknown): data is Action =>
-  isGraphNode(data) ? typeof data.data === 'function' : false;
+  isGraphNode(data) ? typeof data.data === 'function' && data.type === ActionType : false;
 
 export const actionGroupSymbol = Symbol('ActionGroup');
 
@@ -95,8 +145,34 @@ export type ActionGroup<TProperties extends Record<string, any> = Record<string,
 >;
 
 export const isActionGroup = (data: unknown): data is ActionGroup =>
-  isGraphNode(data) ? data.data === actionGroupSymbol : false;
+  isGraphNode(data) ? data.data === actionGroupSymbol && data.type === ActionGroupType : false;
 
 export type ActionLike = Action | ActionGroup;
 
 export const isActionLike = (data: unknown): data is Action | ActionGroup => isAction(data) || isActionGroup(data);
+
+//
+// Node Factories
+//
+
+/** Typed factory for constructing a NodeArg. Provides auto-complete and type validation. */
+export const make = <TData = any, TProperties extends Record<string, any> = Record<string, any>>(
+  arg: NodeArg<TData, TProperties>,
+): NodeArg<TData, TProperties> => arg;
+
+/** Create an action node. Automatically sets `type: ActionType`. */
+export const makeAction = <R = never>(
+  arg: Omit<NodeArg<ActionData<R>>, 'type' | 'nodes' | 'edges'>,
+): NodeArg<ActionData<R>> => ({
+  ...arg,
+  type: ActionType,
+});
+
+/** Create an action group node. Automatically sets `type` and `data`. */
+export const makeActionGroup = (
+  arg: Omit<NodeArg<typeof actionGroupSymbol>, 'type' | 'data' | 'nodes' | 'edges'>,
+): NodeArg<typeof actionGroupSymbol> => ({
+  ...arg,
+  type: ActionGroupType,
+  data: actionGroupSymbol,
+});

package/src/scheduler.browser.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { scheduleTask, yieldOrContinue } from 'main-thread-scheduling';

package/src/scheduler.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// CF Workers / Node fallback: there is no main thread to yield to.
+// scheduleTask runs the callback on the next microtask; yieldOrContinue is a microtask hop.
+
+type ScheduleOptions = { strategy?: 'smooth' | 'interactive' | 'idle'; signal?: AbortSignal };
+
+export const scheduleTask = async <T>(callback: () => T | Promise<T>, _options?: ScheduleOptions): Promise<T> => {
+  await Promise.resolve();
+  return callback();
+};
+
+export const yieldOrContinue = async (_priority: 'smooth' | 'interactive' | 'idle'): Promise<void> => {
+  await Promise.resolve();
+};