@intrig/plugin-react 0.0.1

package/src/lib/templates/docs/sse-hook.spec.ts

@@ -0,0 +1,207 @@
+import { reactSseHookDocs } from './sse-hook';
+
+// We use a plain object cast to any to avoid direct dependency on the types from "@intrig/plugin-sdk" in test.
+
+describe('reactSseHookDocs', () => {
+  it('snapshot — simple REST descriptor (no body, no path params)', async () => {
+    const descriptor = {
+      id: '1',
+      name: 'streamLogs',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'logs',
+      data: {
+        method: 'GET',
+        paths: ['/api/logs/stream'],
+        operationId: 'streamLogs',
+        // no requestBody
+        // no variables
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — request body only (no path params)', async () => {
+    const descriptor = {
+      id: '2',
+      name: 'streamCustomEvents',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'events',
+      data: {
+        method: 'POST',
+        paths: ['/api/events/stream'],
+        operationId: 'streamCustomEvents',
+        requestBody: 'StreamCustomEventsRequest',
+        // no variables
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — path params only (no request body)', async () => {
+    const descriptor = {
+      id: '3',
+      name: 'streamUserActivity',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'users/{userId}/activity',
+      data: {
+        method: 'GET',
+        paths: ['/api/users/{userId}/activity/stream'],
+        operationId: 'streamUserActivity',
+        variables: [
+          { name: 'userId', in: 'path', ref: '#/components/schemas/UserId' },
+        ],
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('snapshot — request body and path params', async () => {
+    const descriptor = {
+      id: '4',
+      name: 'streamTaskProgress',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'tasks/{taskId}/progress',
+      data: {
+        method: 'POST',
+        paths: ['/api/tasks/{taskId}/progress/stream'],
+        operationId: 'streamTaskProgress',
+        requestBody: 'StreamTaskProgressRequest',
+        variables: [
+          { name: 'taskId', in: 'PATH', ref: '#/components/schemas/TaskId' },
+        ],
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles multiple path params', async () => {
+    const descriptor = {
+      id: '5',
+      name: 'streamProjectNotifications',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'projects/{projectId}/notifications/{notificationId}',
+      data: {
+        method: 'GET',
+        paths: ['/api/projects/{projectId}/notifications/{notificationId}/stream'],
+        operationId: 'streamProjectNotifications',
+        variables: [
+          { name: 'projectId', in: 'path', ref: '#/components/schemas/ProjectId' },
+          { name: 'notificationId', in: 'PATH', ref: '#/components/schemas/NotificationId' },
+        ],
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles query params mixed with path params', async () => {
+    const descriptor = {
+      id: '6',
+      name: 'streamSystemMetrics',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'systems/{systemId}/metrics',
+      data: {
+        method: 'GET',
+        paths: ['/api/systems/{systemId}/metrics/stream'],
+        operationId: 'streamSystemMetrics',
+        variables: [
+          { name: 'systemId', in: 'path', ref: '#/components/schemas/SystemId' },
+          { name: 'interval', in: 'query', ref: '#/components/schemas/Interval' },
+          { name: 'includeDetails', in: 'QUERY', ref: '#/components/schemas/Boolean' },
+        ],
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles empty variables array', async () => {
+    const descriptor = {
+      id: '7',
+      name: 'streamGlobalEvents',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'events',
+      data: {
+        method: 'GET',
+        paths: ['/api/events/global/stream'],
+        operationId: 'streamGlobalEvents',
+        variables: [], // empty array instead of undefined
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles case-insensitive path parameter detection', async () => {
+    const descriptor = {
+      id: '8',
+      name: 'streamOrderUpdates',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'orders/{orderId}',
+      data: {
+        method: 'GET',
+        paths: ['/api/orders/{orderId}/updates/stream'],
+        operationId: 'streamOrderUpdates',
+        variables: [
+          { name: 'orderId', in: 'Path', ref: '#/components/schemas/OrderId' }, // Mixed case
+        ],
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+
+  it('handles complex SSE endpoint with body and multiple params', async () => {
+    const descriptor = {
+      id: '9',
+      name: 'streamAnalytics',
+      type: 'rest' as const,
+      source: 'demo_api',
+      path: 'analytics/{dashboardId}/stream',
+      data: {
+        method: 'POST',
+        paths: ['/api/analytics/{dashboardId}/stream'],
+        operationId: 'streamAnalytics',
+        requestBody: 'StreamAnalyticsRequest',
+        variables: [
+          { name: 'dashboardId', in: 'path', ref: '#/components/schemas/DashboardId' },
+          { name: 'real_time', in: 'query', ref: '#/components/schemas/Boolean' },
+          { name: 'format', in: 'query', ref: '#/components/schemas/Format' },
+        ],
+      },
+    };
+
+    const result = await reactSseHookDocs(descriptor as any);
+    expect(result.path).toBe('sse-hook.md');
+    expect(result.content).toMatchSnapshot();
+  });
+});

package/src/lib/templates/docs/sse-hook.ts

@@ -0,0 +1,221 @@
+import { camelCase, mdLiteral, pascalCase, ResourceDescriptor, RestData } from "@intrig/plugin-sdk";
+
+export function reactSseHookDocs(descriptor: ResourceDescriptor<RestData>) {
+  const md = mdLiteral("sse-hook.md");
+
+  // ===== Derived names =====
+  const hasPathParams = (descriptor.data.variables ?? []).some(
+    (v: any) => v.in?.toUpperCase() === "PATH",
+  );
+
+  const actionName = camelCase(descriptor.name);                 // e.g. streamBuildLogs
+  const respVar = `${actionName}Resp`;                           // e.g. streamBuildLogsResp
+  const clearName = `clear${pascalCase(descriptor.name)}`;       // e.g. clearStreamBuildLogs
+
+  const requestBodyVar = descriptor.data.requestBody
+    ? camelCase(descriptor.data.requestBody)
+    : undefined;
+  const requestBodyType = descriptor.data.requestBody
+    ? pascalCase(descriptor.data.requestBody)
+    : undefined;
+
+  const paramsVar = hasPathParams ? `${actionName}Params` : undefined;           // e.g. streamBuildLogsParams
+  const paramsType = hasPathParams ? `${pascalCase(descriptor.name)}Params` : undefined; // e.g. StreamBuildLogsParams
+
+  const responseTypeName = `${pascalCase(descriptor.name)}ResponseBody`; // if generated by your build
+  const callArgs = [requestBodyVar, paramsVar ?? "{}"].filter(Boolean).join(", ");
+
+  return md`
+# Intrig SSE Hooks — Quick Guide
+
+## When should I use the SSE hook?
+- **Your endpoint streams events** (Server-Sent Events) and you want **incremental updates** in the UI → use this **SSE hook**.
+- **You only need a final result** → use the regular **stateful hook**.
+- **One-off validate/submit/update** with no shared state → use the **async hook**.
+
+> Intrig SSE hooks are **stateful hooks** under the hood. **Events arrive while the hook is in \`Pending\`**. When the stream completes, the hook transitions to **\`Success\`** (or **\`Error\`**).
+
+---
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+\`\`\`ts
+import { use${pascalCase(descriptor.name)} } from '@intrig/react/${descriptor.path}/client';
+\`\`\`
+
+### 2) Utility guards
+\`\`\`ts
+import { isPending, isSuccess, isError } from '@intrig/react';
+\`\`\`
+
+### 3) Hook instance (auto-clear on unmount)
+\`\`\`ts
+const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}({ clearOnUnmount: true });
+\`\`\`
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { use${pascalCase(descriptor.name)} } from '@intrig/react/${descriptor.path}/client';
+import { isPending, isSuccess, isError } from '@intrig/react';
+import { useEffect, useState } from 'react';
+
+export default function Example() {
+  const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}({ clearOnUnmount: true });
+  const [messages, setMessages] = useState<any[]>([]);
+
+  useEffect(() => {
+    ${actionName}(${callArgs}); // start stream
+  }, [${actionName}]);
+
+  useEffect(() => {
+    // SSE delivers messages while state is Pending
+    if (isPending(${respVar})) {
+      setMessages((prev) => [...prev, ${respVar}.data]);
+    }
+  }, [${respVar}]);
+
+  if (isError(${respVar})) return <>An error occurred</>;
+  if (isPending(${respVar})) return <pre>{JSON.stringify(messages, null, 2)}</pre>;
+  if (isSuccess(${respVar})) return <>Completed</>;
+
+  return null;
+}
+\`\`\`
+
+${(requestBodyType || paramsType) ? `### Optional types (if generated by your build)
+\`\`\`ts
+${requestBodyType ? `import type { ${requestBodyType} } from '@intrig/react/${descriptor.source}/components/schemas/${requestBodyType}';\n` : ''}${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.params';\n` : ''}import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
+\`\`\`
+` : ''}
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Signature (shape shown; concrete generics vary per generated hook)
+declare function use${pascalCase(descriptor.name)}(options?: {
+  fetchOnMount?: boolean;
+  clearOnUnmount?: boolean;   // recommended for streams
+  key?: string;               // isolate multiple subscriptions
+  params?: ${paramsType ?? 'unknown'};
+  body?: ${requestBodyType ?? 'unknown'};
+}): [
+  // While streaming: isPending(state) === true and state.data is the latest event
+  NetworkState<${responseTypeName} /* or event payload type */, any>,
+  // Start streaming:
+  (req: { params?: ${paramsType ?? 'unknown'}; body?: ${requestBodyType ?? 'unknown'} }) => void,
+  // Clear/close stream:
+  () => void
+];
+\`\`\`
+
+> **Important:** For SSE, **each incoming event** is surfaced as \`${respVar}.data\` **only while** \`isPending(${respVar})\` is true. On stream completion the hook flips to \`isSuccess\`.
+
+---
+
+## Usage patterns
+
+### 1) Lifecycle-bound stream (start on mount, auto-clear)
+\`\`\`tsx
+const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}({ clearOnUnmount: true });
+
+useEffect(() => {
+  ${actionName}(${callArgs});
+}, [${actionName}]);
+\`\`\`
+<details><summary>Description</summary>
+Starts the stream when the component mounts and closes it when the component unmounts.
+</details>
+
+### 2) Collect messages into an array (simple collector)
+\`\`\`tsx
+const [messages, setMessages] = useState<any[]>([]);
+
+useEffect(() => {
+  if (isPending(${respVar})) setMessages((m) => [...m, ${respVar}.data]);
+}, [${respVar}]);
+\`\`\`
+<details><summary>Description</summary>
+Appends each event to an in-memory array. Good for logs and chat-like feeds; consider capping length to avoid memory growth.
+</details>
+
+### 3) Keep only the latest event (cheap UI)
+\`\`\`tsx
+const latest = isPending(${respVar}) ? ${respVar}.data : undefined;
+\`\`\`
+<details><summary>Description</summary>
+When you only need the most recent message (progress percentage, status line).
+</details>
+
+### 4) Controlled start/stop (user-triggered)
+\`\`\`tsx
+const [${respVar}, ${actionName}, ${clearName}] = use${pascalCase(descriptor.name)}();
+
+const start = () => ${actionName}(${callArgs});
+const stop  = () => ${clearName}();
+\`\`\`
+<details><summary>Description</summary>
+Expose play/pause UI for long streams or admin tools.
+</details>
+
+---
+
+## Full example (with flushSync option)
+
+\`\`\`tsx
+import { use${pascalCase(descriptor.name)} } from '@intrig/react/${descriptor.path}/client';
+import { isPending, isSuccess, isError } from '@intrig/react';
+import { useEffect, useState } from 'react';
+import { flushSync } from 'react-dom';
+
+function MyComponent() {
+  const [${respVar}, ${actionName}] = use${pascalCase(descriptor.name)}({ clearOnUnmount: true });
+  const [events, setEvents] = useState<any[]>([]);
+
+  useEffect(() => {
+    ${actionName}(${callArgs});
+  }, [${actionName}]);
+
+  useEffect(() => {
+    if (isPending(${respVar})) {
+      // Use flushSync only if you must render every single event (high-frequency streams).
+      flushSync(() => setEvents((xs) => [...xs, ${respVar}.data]));
+    }
+  }, [${respVar}]);
+
+  if (isError(${respVar})) return <>Stream error</>;
+  return (
+    <>
+      {isPending(${respVar}) && <pre>{JSON.stringify(events, null, 2)}</pre>}
+      {isSuccess(${respVar}) && <>Completed ({events.length} events)</>}
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Tips, anti-patterns & gotchas
+
+- **Prefer \`clearOnUnmount: true\`** so the EventSource/web request is closed when the component disappears.
+- **Don’t store unbounded arrays** for infinite streams—cap the length or batch to IndexedDB.
+- **Avoid unnecessary \`flushSync\`**; it’s expensive. Use it only when you truly must render every event.
+- **Multiple streams:** supply a unique \`key\` to isolate independent subscriptions.
+- **Server requirements:** SSE endpoints should send \`Content-Type: text/event-stream\`, disable buffering, and flush regularly; add relevant CORS headers if needed.
+- **Completion:** UI can switch from progress view (\`isPending\`) to final view (\`isSuccess\`) automatically.
+
+---
+
+## Troubleshooting
+
+- **No intermediate messages:** ensure the server is truly streaming SSE (correct content type + flush) and that proxies/CDNs aren’t buffering responses.
+- **UI not updating for each event:** remove expensive work from the event effect, consider throttling; only use \`flushSync\` if absolutely necessary.
+- **Stream never completes:** check server end conditions and that you call \`${clearName}\` when appropriate.
+
+`;
+}

package/src/lib/templates/extra.template.ts

@@ -0,0 +1,198 @@
+import {typescript} from "@intrig/plugin-sdk";
+import * as path from 'path'
+
+export function reactExtraTemplate() {
+  const ts = typescript(path.resolve("src", "extra.ts"))
+
+  return ts`import {
+  BinaryFunctionHook,
+  BinaryHookOptions,
+  BinaryProduceHook,
+  ConstantHook,
+  error,
+  init,
+  IntrigHook,
+  IntrigHookOptions,
+  isSuccess,
+  NetworkState,
+  pending,
+  success,
+  UnaryFunctionHook,
+  UnaryHookOptions,
+  UnaryProduceHook,
+  UnitHook,
+  UnitHookOptions,
+} from '@intrig/react/network-state';
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+} from 'react';
+import { useIntrigContext } from '@intrig/react/intrig-context';
+
+/**
+ * A custom hook that manages and returns the network state of a promise-based function,
+ * providing a way to execute the function and clear its state.
+ *
+ * @param fn The promise-based function whose network state is to be managed. It should be a function that returns a promise.
+ * @param key An optional identifier for the network state. Defaults to 'default'.
+ * @return A tuple containing the current network state, a function to execute the promise, and a function to clear the state.
+ */
+export function useAsNetworkState<T, F extends (...args: any) => Promise<T>>(
+  fn: F,
+  options: any = {},
+): [NetworkState<T>, (...params: Parameters<F>) => void, () => void] {
+  const id = useId();
+
+  const context = useIntrigContext();
+
+  const key = options.key ?? 'default';
+
+  const networkState = useMemo(() => {
+    return context.state?.[${"`promiseState:${id}:${key}}`"}] ?? init();
+  }, [context.state?.[${"`promiseState:${id}:${key}}`"}]]);
+
+  const dispatch = useCallback(
+    (state: NetworkState<T>) => {
+      context.dispatch({ key, operation: id, source: 'promiseState', state });
+    },
+    [key, context.dispatch],
+  );
+
+  const execute = useCallback((...args: any[]) => {
+    dispatch(pending());
+    return fn(...args).then(
+      (data) => {
+        dispatch(success(data));
+      },
+      (e) => {
+        dispatch(error(e));
+      },
+    );
+  }, []);
+
+  const clear = useCallback(() => {
+    dispatch(init());
+  }, []);
+
+  return [networkState, execute, clear];
+}
+
+/**
+ * A custom hook that resolves the value from the provided hook's state and updates it whenever the state changes.
+ *
+ * @param {IntrigHook<P, B, T>} hook - The hook that provides the state to observe and resolve data from.
+ * @param options
+ * @return {T | undefined} The resolved value from the hook's state or undefined if the state is not successful.
+ */
+export function useResolvedValue(
+  hook: UnitHook,
+  options: UnitHookOptions,
+): undefined;
+
+export function useResolvedValue<T>(
+  hook: ConstantHook<T>,
+  options: UnitHookOptions,
+): T | undefined;
+
+export function useResolvedValue<P>(
+  hook: UnaryProduceHook<P>,
+  options: UnaryHookOptions<P>,
+): undefined;
+
+export function useResolvedValue<P, T>(
+  hook: UnaryFunctionHook<P, T>,
+  options: UnaryHookOptions<P>,
+): T | undefined;
+
+export function useResolvedValue<P, B>(
+  hook: BinaryProduceHook<P, B>,
+  options: BinaryHookOptions<P, B>,
+): undefined;
+
+export function useResolvedValue<P, B, T>(
+  hook: BinaryFunctionHook<P, B, T>,
+  options: BinaryHookOptions<P, B>,
+): T | undefined;
+
+// **Implementation**
+export function useResolvedValue<P, B, T>(
+  hook: IntrigHook<P, B, T>,
+  options: IntrigHookOptions<P, B>,
+): T | undefined {
+  const [value, setValue] = useState<T | undefined>();
+
+  const [state] = hook(options as any); // Ensure compatibility with different hook types
+
+  useEffect(() => {
+    if (isSuccess(state)) {
+      setValue(state.data);
+    } else {
+      setValue(undefined);
+    }
+  }, [state]);
+
+  return value;
+}
+
+/**
+ * A custom hook that resolves and caches the value from a successful state provided by the given hook.
+ * The state is updated only when it is in a successful state.
+ *
+ * @param {IntrigHook<P, B, T>} hook - The hook that provides the state to observe and cache data from.
+ * @param options
+ * @return {T | undefined} The cached value from the hook's state or undefined if the state is not successful.
+ */
+export function useResolvedCachedValue(
+  hook: UnitHook,
+  options: UnitHookOptions,
+): undefined;
+
+export function useResolvedCachedValue<T>(
+  hook: ConstantHook<T>,
+  options: UnitHookOptions,
+): T | undefined;
+
+export function useResolvedCachedValue<P>(
+  hook: UnaryProduceHook<P>,
+  options: UnaryHookOptions<P>,
+): undefined;
+
+export function useResolvedCachedValue<P, T>(
+  hook: UnaryFunctionHook<P, T>,
+  options: UnaryHookOptions<P>,
+): T | undefined;
+
+export function useResolvedCachedValue<P, B>(
+  hook: BinaryProduceHook<P, B>,
+  options: BinaryHookOptions<P, B>,
+): undefined;
+
+export function useResolvedCachedValue<P, B, T>(
+  hook: BinaryFunctionHook<P, B, T>,
+  options: BinaryHookOptions<P, B>,
+): T | undefined;
+
+// **Implementation**
+export function useResolvedCachedValue<P, B, T>(
+  hook: IntrigHook<P, B, T>,
+  options: IntrigHookOptions<P, B>,
+): T | undefined {
+  const [cachedValue, setCachedValue] = useState<T | undefined>();
+
+  const [state] = hook(options as any); // Ensure compatibility with different hook types
+
+  useEffect(() => {
+    if (isSuccess(state)) {
+      setCachedValue(state.data);
+    }
+    // Do not clear cached value if state is unsuccessful
+  }, [state]);
+
+  return cachedValue;
+}
+
+`
+}

package/src/lib/templates/index.template.ts

@@ -0,0 +1,14 @@
+import {typescript} from "@intrig/plugin-sdk";
+import * as path from 'path'
+
+export function indexTemplate(){
+
+  const ts = typescript(path.resolve("src", "index.ts"))
+
+  return ts`
+  export * from './intrig-provider-main';
+  export * from './network-state';
+  export * from './extra';
+  export * from './media-type-utils';
+  `
+}

package/src/lib/templates/intrigMiddleware.template.ts

@@ -0,0 +1,21 @@
+import { typescript } from "@intrig/plugin-sdk";
+import * as path from 'path'
+
+export function intrigMiddlewareTemplate() {
+  const ts = typescript(path.resolve('src', 'intrig-middleware.ts'))
+
+  return ts`
+import axios from 'axios';
+import { requestInterceptor } from 'intrig-hook';
+
+export function getAxiosInstance(key: string) {
+  let axiosInstance = axios.create({
+    baseURL: process.env[${"`${key.toUpperCase()}_API_URL`"}],
+  });
+
+  axiosInstance.interceptors.request.use(requestInterceptor);
+
+  return axiosInstance;
+}
+`
+}