opentasks 0.0.1 → 0.0.2

package/dist/graph/provider-store.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Provider-Aware Graph Store
+ *
+ * Extends GraphStore with provider resolution and materialization capabilities.
+ * This wrapper adds the ability to resolve external URIs and materialize
+ * external nodes while keeping the base GraphStore implementation intact.
+ */
+import type { Node, ExternalNode } from '../schema/index.js';
+import type { ProviderNode, ProviderRegistry, MaterializationConfig, ProviderOperationContext } from '../providers/types.js';
+import type { MaterializationManager } from '../providers/materialization.js';
+import { type ProviderChangeEvent } from '../providers/traits/Watchable.js';
+import { type TaskAction, type ReadyTaskOptions } from '../providers/traits/TaskManageable.js';
+import type { GraphStore } from './store.js';
+import type { CreateNodeInput, UpdateNodeInput, DeleteOptions } from './types.js';
+/**
+ * Options for resolving a node
+ */
+export interface ResolveOptions {
+    /** Force fresh fetch (ignore cache) */
+    refresh?: boolean;
+    /** Explicitly request materialization */
+    materialize?: boolean;
+    /** Include raw provider data in response */
+    includeRawData?: boolean;
+}
+/**
+ * Options for provider-routed create
+ */
+export interface ProviderCreateOptions {
+    /** Target provider scheme (overrides defaultProvider) */
+    scheme?: string;
+    /** Operational context forwarded to the provider */
+    context?: ProviderOperationContext;
+}
+/**
+ * Options for provider-routed get
+ */
+export interface ProviderGetOptions {
+    /** Operational context forwarded to the provider */
+    context?: ProviderOperationContext;
+}
+/**
+ * Options for provider-routed update
+ */
+export interface ProviderUpdateOptions {
+    /** Operational context forwarded to the provider */
+    context?: ProviderOperationContext;
+}
+/**
+ * Options for task transition operations
+ */
+export interface TaskTransitionOptions {
+    /** Operational context forwarded to the provider */
+    context?: ProviderOperationContext;
+}
+/**
+ * Options for querying ready tasks across providers
+ */
+export interface FederatedReadyTaskOptions extends ReadyTaskOptions {
+    /** Only query these providers (by name). If omitted, queries all task-capable providers. */
+    providers?: string[];
+    /** Operational context forwarded to providers */
+    context?: ProviderOperationContext;
+}
+/**
+ * Result from a task transition
+ */
+export interface TaskTransitionResult {
+    /** The updated node (materialized if external) */
+    node: Node;
+    /** The provider that handled the transition */
+    provider: string;
+    /** The action that was applied */
+    action: TaskAction;
+}
+/**
+ * Result from a provider-routed create
+ */
+export interface ProviderCreateResult {
+    /** The created/materialized node */
+    node: Node;
+    /** The provider URI (if created via external provider) */
+    uri?: string;
+    /** Which provider handled the create */
+    provider: string;
+}
+/**
+ * Configuration for provider-aware store
+ */
+export interface ProviderStoreConfig {
+    /** Pre-configured provider registry (optional) */
+    registry?: ProviderRegistry;
+    /** Materialization configuration */
+    materialization?: Partial<MaterializationConfig>;
+    /** Whether to auto-register native provider (default: true) */
+    autoRegisterNative?: boolean;
+    /** Default provider for CRUD operations ('native' = local GraphStore) */
+    defaultProvider?: string;
+}
+/**
+ * Callback for provider change events received by the store.
+ * Allows external consumers to react to provider-driven changes.
+ */
+export type ProviderChangeHandler = (providerName: string, event: ProviderChangeEvent) => void;
+/**
+ * Provider-aware graph store interface
+ */
+export interface ProviderAwareStore extends GraphStore {
+    /** Provider registry */
+    readonly providers: ProviderRegistry;
+    /** Materialization manager */
+    readonly materialization: MaterializationManager;
+    /**
+     * Resolve any node by ID or URI
+     * - Local IDs (s-, i-, f-, e-, x-) → getNode()
+     * - External URIs → provider.get() + optional materialize
+     */
+    resolveNode(idOrUri: string, options?: ResolveOptions): Promise<Node | ProviderNode | null>;
+    /**
+     * Materialize an external node from provider data
+     */
+    materializeNode(uri: string): Promise<ExternalNode>;
+    /**
+     * Refresh a materialized external node
+     */
+    refreshNode(id: string): Promise<ExternalNode | null>;
+    /**
+     * Start background sync for external nodes
+     */
+    startBackgroundSync(): void;
+    /**
+     * Stop background sync
+     */
+    stopBackgroundSync(): void;
+    /**
+     * Check if background sync is running
+     */
+    isBackgroundSyncRunning(): boolean;
+    /**
+     * Start watching all watchable providers for changes.
+     *
+     * For each provider that implements the Watchable trait, subscribes
+     * to change events and auto-refreshes materialized nodes.
+     * Non-watchable providers are skipped (use startBackgroundSync for those).
+     */
+    startProviderWatching(): void;
+    /**
+     * Stop watching all providers for changes.
+     */
+    stopProviderWatching(): void;
+    /**
+     * Register an external handler for provider change events.
+     * Called after the store has processed each event internally.
+     *
+     * @returns Unsubscribe function
+     */
+    onProviderChange(handler: ProviderChangeHandler): () => void;
+    /**
+     * Create a node via provider dispatch.
+     * Routes to defaultProvider or explicit scheme. Always materializes.
+     */
+    providerCreate(input: CreateNodeInput, options?: ProviderCreateOptions): Promise<ProviderCreateResult>;
+    /**
+     * Get a node by local ID or provider URI.
+     * For external nodes, refreshes if stale.
+     */
+    providerGet(idOrUri: string, options?: ProviderGetOptions): Promise<Node | null>;
+    /**
+     * Update a node by local ID or provider URI.
+     * For external/materialized nodes, routes update to the owning provider
+     * and refreshes the local materialized copy.
+     */
+    providerUpdate(idOrUri: string, updates: UpdateNodeInput, options?: ProviderUpdateOptions): Promise<Node>;
+    /**
+     * Delete a node by local ID or provider URI.
+     * For external/materialized nodes, deletes in the provider
+     * and removes the local materialized copy.
+     */
+    providerDelete(idOrUri: string, options?: DeleteOptions & {
+        context?: ProviderOperationContext;
+    }): Promise<void>;
+    /** The configured default provider name */
+    readonly defaultProvider: string;
+    /**
+     * Transition a task's status using a semantic action.
+     * Resolves the owning provider, checks that it supports TaskManageable,
+     * and delegates the transition.
+     */
+    taskTransition(idOrUri: string, action: TaskAction, options?: TaskTransitionOptions): Promise<TaskTransitionResult>;
+    /**
+     * Get tasks that are ready to work on, aggregated across all
+     * task-capable providers (Option B: federated aggregation).
+     */
+    taskReady(options?: FederatedReadyTaskOptions): Promise<Node[]>;
+    /**
+     * Assign a task to an owner.
+     * Resolves the owning provider, checks TaskManageable + supportsAssignment.
+     */
+    taskAssign(idOrUri: string, assignee: string, options?: TaskTransitionOptions): Promise<Node>;
+    /**
+     * Get valid next actions for a task in its current state.
+     * Falls back to the provider's full `taskCapabilities.actions` if the
+     * provider doesn't implement `validActions`.
+     */
+    taskValidActions(idOrUri: string): Promise<TaskAction[]>;
+}
+/**
+ * Create a provider-aware store by wrapping an existing GraphStore
+ */
+export declare function createProviderAwareStore(baseStore: GraphStore, config?: ProviderStoreConfig): ProviderAwareStore;
+//# sourceMappingURL=provider-store.d.ts.map

package/dist/graph/provider-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-store.d.ts","sourceRoot":"","sources":["../../src/graph/provider-store.ts"],"names":[],"mappings":"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"}