@objectstack/client-react 0.6.1

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * @objectstack/client-react
+ *
+ * React hooks for ObjectStack Client SDK
+ *
+ * Provides type-safe React hooks for:
+ * - Data queries (useQuery, useMutation, usePagination, useInfiniteQuery)
+ * - Metadata access (useObject, useView, useFields, useMetadata)
+ * - Client context (ObjectStackProvider, useClient)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectStackClient = exports.useMetadata = exports.useFields = exports.useView = exports.useObject = exports.useInfiniteQuery = exports.usePagination = exports.useMutation = exports.useQuery = exports.useClient = exports.ObjectStackContext = exports.ObjectStackProvider = void 0;
+// Context & Provider
+var context_1 = require("./context");
+Object.defineProperty(exports, "ObjectStackProvider", { enumerable: true, get: function () { return context_1.ObjectStackProvider; } });
+Object.defineProperty(exports, "ObjectStackContext", { enumerable: true, get: function () { return context_1.ObjectStackContext; } });
+Object.defineProperty(exports, "useClient", { enumerable: true, get: function () { return context_1.useClient; } });
+// Data Hooks
+var data_hooks_1 = require("./data-hooks");
+Object.defineProperty(exports, "useQuery", { enumerable: true, get: function () { return data_hooks_1.useQuery; } });
+Object.defineProperty(exports, "useMutation", { enumerable: true, get: function () { return data_hooks_1.useMutation; } });
+Object.defineProperty(exports, "usePagination", { enumerable: true, get: function () { return data_hooks_1.usePagination; } });
+Object.defineProperty(exports, "useInfiniteQuery", { enumerable: true, get: function () { return data_hooks_1.useInfiniteQuery; } });
+// Metadata Hooks
+var metadata_hooks_1 = require("./metadata-hooks");
+Object.defineProperty(exports, "useObject", { enumerable: true, get: function () { return metadata_hooks_1.useObject; } });
+Object.defineProperty(exports, "useView", { enumerable: true, get: function () { return metadata_hooks_1.useView; } });
+Object.defineProperty(exports, "useFields", { enumerable: true, get: function () { return metadata_hooks_1.useFields; } });
+Object.defineProperty(exports, "useMetadata", { enumerable: true, get: function () { return metadata_hooks_1.useMetadata; } });
+// Re-export ObjectStackClient and types from @objectstack/client
+var client_1 = require("@objectstack/client");
+Object.defineProperty(exports, "ObjectStackClient", { enumerable: true, get: function () { return client_1.ObjectStackClient; } });

package/dist/metadata-hooks.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Metadata Hooks
+ *
+ * React hooks for accessing ObjectStack metadata (schemas, views, fields)
+ */
+import { useClient } from './context';
+/**
+ * Metadata query options
+ */
+export interface UseMetadataOptions {
+    /** Enable/disable automatic query execution */
+    enabled?: boolean;
+    /** Use cached metadata if available */
+    useCache?: boolean;
+    /** ETag for conditional requests */
+    ifNoneMatch?: string;
+    /** If-Modified-Since header for conditional requests */
+    ifModifiedSince?: string;
+    /** Callback on successful query */
+    onSuccess?: (data: any) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Metadata query result
+ */
+export interface UseMetadataResult<T = any> {
+    /** Metadata data */
+    data: T | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Refetch the metadata */
+    refetch: () => Promise<void>;
+    /** ETag from last fetch */
+    etag?: string;
+    /** Whether data came from cache (304 Not Modified) */
+    fromCache: boolean;
+}
+/**
+ * Hook for fetching object schema/metadata
+ *
+ * @example
+ * ```tsx
+ * function ObjectSchemaViewer({ objectName }: { objectName: string }) {
+ *   const { data: schema, isLoading, error } = useObject(objectName);
+ *
+ *   if (isLoading) return <div>Loading schema...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>{schema.label}</h2>
+ *       <p>Fields: {Object.keys(schema.fields).length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useObject(objectName: string, options?: UseMetadataOptions): UseMetadataResult;
+/**
+ * Hook for fetching view configuration
+ *
+ * @example
+ * ```tsx
+ * function ViewConfiguration({ objectName }: { objectName: string }) {
+ *   const { data: view, isLoading } = useView(objectName, 'list');
+ *
+ *   if (isLoading) return <div>Loading view...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h3>List View for {objectName}</h3>
+ *       <p>Columns: {view?.columns?.length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useView(objectName: string, viewType?: 'list' | 'form', options?: UseMetadataOptions): UseMetadataResult;
+/**
+ * Hook for extracting fields from object schema
+ *
+ * @example
+ * ```tsx
+ * function FieldList({ objectName }: { objectName: string }) {
+ *   const { data: fields, isLoading } = useFields(objectName);
+ *
+ *   if (isLoading) return <div>Loading fields...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {fields?.map(field => (
+ *         <li key={field.name}>{field.label} ({field.type})</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFields(objectName: string, options?: UseMetadataOptions): UseMetadataResult<any[]>;
+/**
+ * Generic metadata hook for custom metadata queries
+ *
+ * @example
+ * ```tsx
+ * function CustomMetadata() {
+ *   const { data, isLoading } = useMetadata(async (client) => {
+ *     // Custom metadata fetching logic
+ *     const object = await client.meta.getObject('custom_object');
+ *     const view = await client.meta.getView('custom_object', 'list');
+ *     return { object, view };
+ *   });
+ *
+ *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
+ * }
+ * ```
+ */
+export declare function useMetadata<T = any>(fetcher: (client: ReturnType<typeof useClient>) => Promise<T>, options?: Omit<UseMetadataOptions, 'useCache' | 'ifNoneMatch' | 'ifModifiedSince'>): UseMetadataResult<T>;
+//# sourceMappingURL=metadata-hooks.d.ts.map

package/dist/metadata-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-hooks.d.ts","sourceRoot":"","sources":["../src/metadata-hooks.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,GAAG;IACxC,oBAAoB;IACpB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,oBAAoB;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAyEnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAM,GAAG,MAAe,EAClC,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CA0CnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAc1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EACjC,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7D,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,aAAa,GAAG,iBAAiB,CAAM,GACrF,iBAAiB,CAAC,CAAC,CAAC,CA0CtB"}

package/dist/metadata-hooks.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Metadata Hooks
+ *
+ * React hooks for accessing ObjectStack metadata (schemas, views, fields)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useObject = useObject;
+exports.useView = useView;
+exports.useFields = useFields;
+exports.useMetadata = useMetadata;
+const react_1 = require("react");
+const context_1 = require("./context");
+/**
+ * Hook for fetching object schema/metadata
+ *
+ * @example
+ * ```tsx
+ * function ObjectSchemaViewer({ objectName }: { objectName: string }) {
+ *   const { data: schema, isLoading, error } = useObject(objectName);
+ *
+ *   if (isLoading) return <div>Loading schema...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>{schema.label}</h2>
+ *       <p>Fields: {Object.keys(schema.fields).length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useObject(objectName, options = {}) {
+    const client = (0, context_1.useClient)();
+    const [data, setData] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [etag, setEtag] = (0, react_1.useState)();
+    const [fromCache, setFromCache] = (0, react_1.useState)(false);
+    const { enabled = true, useCache = true, ifNoneMatch, ifModifiedSince, onSuccess, onError } = options;
+    const fetchMetadata = (0, react_1.useCallback)(async () => {
+        if (!enabled)
+            return;
+        try {
+            setIsLoading(true);
+            setError(null);
+            setFromCache(false);
+            if (useCache) {
+                // Use cached metadata endpoint
+                const result = await client.meta.getCached(objectName, {
+                    ifNoneMatch: ifNoneMatch || etag,
+                    ifModifiedSince
+                });
+                if (result.notModified) {
+                    setFromCache(true);
+                }
+                else {
+                    setData(result.data);
+                    if (result.etag) {
+                        setEtag(result.etag.value);
+                    }
+                }
+                onSuccess?.(result.data || data);
+            }
+            else {
+                // Direct fetch without cache
+                const result = await client.meta.getObject(objectName);
+                setData(result);
+                onSuccess?.(result);
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Failed to fetch object metadata');
+            setError(error);
+            onError?.(error);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, objectName, enabled, useCache, ifNoneMatch, ifModifiedSince, etag, data, onSuccess, onError]);
+    (0, react_1.useEffect)(() => {
+        fetchMetadata();
+    }, [fetchMetadata]);
+    const refetch = (0, react_1.useCallback)(async () => {
+        await fetchMetadata();
+    }, [fetchMetadata]);
+    return {
+        data,
+        isLoading,
+        error,
+        refetch,
+        etag,
+        fromCache
+    };
+}
+/**
+ * Hook for fetching view configuration
+ *
+ * @example
+ * ```tsx
+ * function ViewConfiguration({ objectName }: { objectName: string }) {
+ *   const { data: view, isLoading } = useView(objectName, 'list');
+ *
+ *   if (isLoading) return <div>Loading view...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h3>List View for {objectName}</h3>
+ *       <p>Columns: {view?.columns?.length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useView(objectName, viewType = 'list', options = {}) {
+    const client = (0, context_1.useClient)();
+    const [data, setData] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const { enabled = true, onSuccess, onError } = options;
+    const fetchView = (0, react_1.useCallback)(async () => {
+        if (!enabled)
+            return;
+        try {
+            setIsLoading(true);
+            setError(null);
+            const result = await client.meta.getView(objectName, viewType);
+            setData(result);
+            onSuccess?.(result);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Failed to fetch view configuration');
+            setError(error);
+            onError?.(error);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, objectName, viewType, enabled, onSuccess, onError]);
+    (0, react_1.useEffect)(() => {
+        fetchView();
+    }, [fetchView]);
+    const refetch = (0, react_1.useCallback)(async () => {
+        await fetchView();
+    }, [fetchView]);
+    return {
+        data,
+        isLoading,
+        error,
+        refetch,
+        fromCache: false
+    };
+}
+/**
+ * Hook for extracting fields from object schema
+ *
+ * @example
+ * ```tsx
+ * function FieldList({ objectName }: { objectName: string }) {
+ *   const { data: fields, isLoading } = useFields(objectName);
+ *
+ *   if (isLoading) return <div>Loading fields...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {fields?.map(field => (
+ *         <li key={field.name}>{field.label} ({field.type})</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+function useFields(objectName, options = {}) {
+    const objectResult = useObject(objectName, options);
+    const fields = objectResult.data?.fields
+        ? Object.entries(objectResult.data.fields).map(([name, field]) => ({
+            name,
+            ...field
+        }))
+        : null;
+    return {
+        ...objectResult,
+        data: fields
+    };
+}
+/**
+ * Generic metadata hook for custom metadata queries
+ *
+ * @example
+ * ```tsx
+ * function CustomMetadata() {
+ *   const { data, isLoading } = useMetadata(async (client) => {
+ *     // Custom metadata fetching logic
+ *     const object = await client.meta.getObject('custom_object');
+ *     const view = await client.meta.getView('custom_object', 'list');
+ *     return { object, view };
+ *   });
+ *
+ *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
+ * }
+ * ```
+ */
+function useMetadata(fetcher, options = {}) {
+    const client = (0, context_1.useClient)();
+    const [data, setData] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const { enabled = true, onSuccess, onError } = options;
+    const fetchMetadata = (0, react_1.useCallback)(async () => {
+        if (!enabled)
+            return;
+        try {
+            setIsLoading(true);
+            setError(null);
+            const result = await fetcher(client);
+            setData(result);
+            onSuccess?.(result);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Failed to fetch metadata');
+            setError(error);
+            onError?.(error);
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, fetcher, enabled, onSuccess, onError]);
+    (0, react_1.useEffect)(() => {
+        fetchMetadata();
+    }, [fetchMetadata]);
+    const refetch = (0, react_1.useCallback)(async () => {
+        await fetchMetadata();
+    }, [fetchMetadata]);
+    return {
+        data,
+        isLoading,
+        error,
+        refetch,
+        fromCache: false
+    };
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@objectstack/client-react",
+  "version": "0.6.1",
+  "description": "React hooks for ObjectStack Client SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "dependencies": {
+    "@objectstack/client": "0.6.1",
+    "@objectstack/spec": "0.6.1",
+    "@objectstack/core": "0.6.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/context.tsx

@@ -0,0 +1,66 @@
+/**
+ * ObjectStack React Context
+ * 
+ * Provides ObjectStackClient instance to React components via Context API
+ */
+
+import * as React from 'react';
+import { createContext, useContext, ReactNode } from 'react';
+import { ObjectStackClient } from '@objectstack/client';
+
+export interface ObjectStackProviderProps {
+  client: ObjectStackClient;
+  children: ReactNode;
+}
+
+export const ObjectStackContext = createContext<ObjectStackClient | null>(null);
+
+/**
+ * Provider component that makes ObjectStackClient available to all child components
+ * 
+ * @example
+ * ```tsx
+ * const client = new ObjectStackClient({ baseUrl: 'http://localhost:3000' });
+ * 
+ * function App() {
+ *   return (
+ *     <ObjectStackProvider client={client}>
+ *       <YourComponents />
+ *     </ObjectStackProvider>
+ *   );
+ * }
+ * ```
+ */
+export function ObjectStackProvider({ client, children }: ObjectStackProviderProps) {
+  return (
+    <ObjectStackContext.Provider value={client}>
+      {children}
+    </ObjectStackContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the ObjectStackClient instance from context
+ * 
+ * @throws Error if used outside of ObjectStackProvider
+ * 
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const client = useClient();
+ *   // Use client.data.find(), etc.
+ * }
+ * ```
+ */
+export function useClient(): ObjectStackClient {
+  const client = useContext(ObjectStackContext);
+  
+  if (!client) {
+    throw new Error(
+      'useClient must be used within an ObjectStackProvider. ' +
+      'Make sure your component is wrapped with <ObjectStackProvider client={...}>.'
+    );
+  }
+  
+  return client;
+}