@arcanejs/react-toolkit 0.13.0 → 0.14.0

package/dist/data.d.mts

@@ -17,6 +17,8 @@ type DataFileUsage = WithPathChange & {
      * this will be relative to the current working directory.
      */
     path: string;
+    /** Callback that will be called if any error occurs during loading or saving the file */
+    onError?: (error: ArcaneDataFileError) => void;
 };
 type ProviderProps = DataFileUsage & {
     children: ReactNode;
@@ -93,10 +95,18 @@ type DataState<T> = {
     status: 'ready';
     data: T;
 });
+type DataFileOperation = 'load' | 'save' | 'usage';
+declare class ArcaneDataFileError extends Error {
+    readonly operation: DataFileOperation;
+    readonly path: string | null;
+    constructor(message: string, operation: DataFileOperation, path: string | null, cause?: unknown);
+}
+type ErrorListener = (error: ArcaneDataFileError) => void;
 type UseDataFileCoreProps<T> = WithPathChange & {
     schema: ZodType<T>;
     defaultValue: T;
     path: string;
+    onError?: (error: ArcaneDataFileError) => void;
 };
 type DataFileCore<T> = {
     data: DataState<T>;
@@ -106,11 +116,11 @@ type DataFileCore<T> = {
 /**
  * Primary hook for & logic for using data files.
  */
-declare function useDataFileCore<T>({ schema, defaultValue, path, onPathChange, }: UseDataFileCoreProps<T>): DataFileCore<T>;
+declare function useDataFileCore<T>({ schema, defaultValue, path, onPathChange, onError, }: UseDataFileCoreProps<T>): DataFileCore<T>;
 type CreateDataFileDefinitionProps<T extends ZodType> = {
     schema: T;
     defaultValue: z.infer<T>;
 };
 declare function createDataFileDefinition<T extends ZodType>({ schema, defaultValue, }: CreateDataFileDefinitionProps<T>): DataFileDefinition<z.infer<T>>;
 
-export { type CreateDataFileDefinitionProps, type DataFileContext, type DataFileCore, type DataFileDefinition, type DataFileUpdater, type DataState, type ProviderProps, type UseDataFileCoreProps, createDataFileDefinition, useDataFile, useDataFileContext, useDataFileCore, useDataFileData, useDataFileUpdater };
+export { ArcaneDataFileError, type CreateDataFileDefinitionProps, type DataFileContext, type DataFileCore, type DataFileDefinition, type DataFileOperation, type DataFileUpdater, type DataState, type ErrorListener, type ProviderProps, type UseDataFileCoreProps, createDataFileDefinition, useDataFile, useDataFileContext, useDataFileCore, useDataFileData, useDataFileUpdater };

package/dist/data.d.ts

@@ -17,6 +17,8 @@ type DataFileUsage = WithPathChange & {
      * this will be relative to the current working directory.
      */
     path: string;
+    /** Callback that will be called if any error occurs during loading or saving the file */
+    onError?: (error: ArcaneDataFileError) => void;
 };
 type ProviderProps = DataFileUsage & {
     children: ReactNode;
@@ -93,10 +95,18 @@ type DataState<T> = {
     status: 'ready';
     data: T;
 });
+type DataFileOperation = 'load' | 'save' | 'usage';
+declare class ArcaneDataFileError extends Error {
+    readonly operation: DataFileOperation;
+    readonly path: string | null;
+    constructor(message: string, operation: DataFileOperation, path: string | null, cause?: unknown);
+}
+type ErrorListener = (error: ArcaneDataFileError) => void;
 type UseDataFileCoreProps<T> = WithPathChange & {
     schema: ZodType<T>;
     defaultValue: T;
     path: string;
+    onError?: (error: ArcaneDataFileError) => void;
 };
 type DataFileCore<T> = {
     data: DataState<T>;
@@ -106,11 +116,11 @@ type DataFileCore<T> = {
 /**
  * Primary hook for & logic for using data files.
  */
-declare function useDataFileCore<T>({ schema, defaultValue, path, onPathChange, }: UseDataFileCoreProps<T>): DataFileCore<T>;
+declare function useDataFileCore<T>({ schema, defaultValue, path, onPathChange, onError, }: UseDataFileCoreProps<T>): DataFileCore<T>;
 type CreateDataFileDefinitionProps<T extends ZodType> = {
     schema: T;
     defaultValue: z.infer<T>;
 };
 declare function createDataFileDefinition<T extends ZodType>({ schema, defaultValue, }: CreateDataFileDefinitionProps<T>): DataFileDefinition<z.infer<T>>;
 
-export { type CreateDataFileDefinitionProps, type DataFileContext, type DataFileCore, type DataFileDefinition, type DataFileUpdater, type DataState, type ProviderProps, type UseDataFileCoreProps, createDataFileDefinition, useDataFile, useDataFileContext, useDataFileCore, useDataFileData, useDataFileUpdater };
+export { ArcaneDataFileError, type CreateDataFileDefinitionProps, type DataFileContext, type DataFileCore, type DataFileDefinition, type DataFileOperation, type DataFileUpdater, type DataState, type ErrorListener, type ProviderProps, type UseDataFileCoreProps, createDataFileDefinition, useDataFile, useDataFileContext, useDataFileCore, useDataFileData, useDataFileUpdater };

package/dist/data.js

@@ -27,11 +27,20 @@ function useDataFileContext(dataFile) {
 function useDataFile(dataFile, usage) {
   return dataFile.useDataFile(usage);
 }
+var ArcaneDataFileError = class extends Error {
+  constructor(message, operation, path, cause) {
+    super(message, { cause });
+    this.operation = operation;
+    this.path = path;
+    this.name = `ArcaneDataFileError(${operation})`;
+  }
+};
 function useDataFileCore({
   schema,
   defaultValue,
   path,
-  onPathChange = "defaultValue"
+  onPathChange = "defaultValue",
+  onError
 }) {
   const log = _chunkRT2VSMJLjs.useLogger.call(void 0, );
   const state = _react.useRef.call(void 0, {
@@ -48,9 +57,13 @@ function useDataFileCore({
     if (!state.current.initialized) {
       state.current.initialized = true;
     } else {
-      throw new Error(
-        "Cannot change schema or defaultValue after initialization"
+      const error = new ArcaneDataFileError(
+        "Cannot change schema or defaultValue after initialization",
+        "usage",
+        null
       );
+      _optionalChain([onError, 'optionalCall', _ => _(error)]);
+      throw error;
     }
   }, [schema, defaultValue]);
   const [data, setData] = _react.useState.call(void 0, {
@@ -104,7 +117,14 @@ function useDataFileCore({
           if (state.current.path === currentPath && state.current.data === currentData) {
             state.current.state = { state: "saved" };
           }
-        } catch (error) {
+        } catch (cause) {
+          const error = new ArcaneDataFileError(
+            `Error saving data file to path: ${currentPath}`,
+            "save",
+            currentPath,
+            cause
+          );
+          _optionalChain([onError, 'optionalCall', _2 => _2(error)]);
           if (state.current.path === currentPath && state.current.data === currentData) {
             state.current.state = { state: "error", error };
             updateDataFromState();
@@ -140,16 +160,16 @@ function useDataFileCore({
         state.current.state = { state: "saved" };
         updateDataFromState();
       }
-    }).catch((error) => {
+    }).catch((err) => {
       if (state.current.path !== path) {
         return;
       }
-      if (error.code === "ENOENT") {
+      if (err.code === "ENOENT") {
         const initialData = onPathChange === "transfer" && state.current.previousData !== void 0 ? state.current.previousData : defaultValue;
         state.current.data = initialData;
         state.current.lastUpdatedMillis = Date.now();
         state.current.state = { state: "dirty" };
-        _optionalChain([log, 'optionalAccess', _ => _.info, 'call', _2 => _2(
+        _optionalChain([log, 'optionalAccess', _3 => _3.info, 'call', _4 => _4(
           "Creating a new file at %s with initial data %o",
           path,
           initialData
@@ -158,6 +178,14 @@ function useDataFileCore({
         updateDataFromState();
         return;
       }
+      const error = new ArcaneDataFileError(
+        `Error loading data file at path: ${path}`,
+        "load",
+        path,
+        err
+      );
+      _optionalChain([onError, 'optionalCall', _5 => _5(error)]);
+      _optionalChain([log, 'optionalAccess', _6 => _6.error, 'call', _7 => _7(error)]);
       state.current.state = { state: "error", error };
       updateDataFromState();
     });
@@ -202,17 +230,25 @@ function createDataFileDefinition({
   });
   const useDataFile2 = ({
     path,
-    onPathChange
+    onPathChange,
+    onError
   }) => useDataFileCore({
     schema,
     defaultValue,
     path,
-    onPathChange
+    onPathChange,
+    onError
   });
-  const Provider = ({ path, onPathChange, children }) => {
+  const Provider = ({
+    path,
+    onPathChange,
+    onError,
+    children
+  }) => {
     const { data, updateData, saveData } = useDataFile2({
       path,
-      onPathChange
+      onPathChange,
+      onError
     });
     const providedContext = _react.useMemo.call(void 0, 
       () => ({
@@ -243,4 +279,5 @@ function createDataFileDefinition({
 
 
 
-exports.createDataFileDefinition = createDataFileDefinition; exports.useDataFile = useDataFile; exports.useDataFileContext = useDataFileContext; exports.useDataFileCore = useDataFileCore; exports.useDataFileData = useDataFileData; exports.useDataFileUpdater = useDataFileUpdater;
+
+exports.ArcaneDataFileError = ArcaneDataFileError; exports.createDataFileDefinition = createDataFileDefinition; exports.useDataFile = useDataFile; exports.useDataFileContext = useDataFileContext; exports.useDataFileCore = useDataFileCore; exports.useDataFileData = useDataFileData; exports.useDataFileUpdater = useDataFileUpdater;

package/dist/data.mjs

@@ -27,11 +27,20 @@ function useDataFileContext(dataFile) {
 function useDataFile(dataFile, usage) {
   return dataFile.useDataFile(usage);
 }
+var ArcaneDataFileError = class extends Error {
+  constructor(message, operation, path, cause) {
+    super(message, { cause });
+    this.operation = operation;
+    this.path = path;
+    this.name = `ArcaneDataFileError(${operation})`;
+  }
+};
 function useDataFileCore({
   schema,
   defaultValue,
   path,
-  onPathChange = "defaultValue"
+  onPathChange = "defaultValue",
+  onError
 }) {
   const log = useLogger();
   const state = useRef({
@@ -48,9 +57,13 @@ function useDataFileCore({
     if (!state.current.initialized) {
       state.current.initialized = true;
     } else {
-      throw new Error(
-        "Cannot change schema or defaultValue after initialization"
+      const error = new ArcaneDataFileError(
+        "Cannot change schema or defaultValue after initialization",
+        "usage",
+        null
       );
+      onError?.(error);
+      throw error;
     }
   }, [schema, defaultValue]);
   const [data, setData] = useState({
@@ -104,7 +117,14 @@ function useDataFileCore({
           if (state.current.path === currentPath && state.current.data === currentData) {
             state.current.state = { state: "saved" };
           }
-        } catch (error) {
+        } catch (cause) {
+          const error = new ArcaneDataFileError(
+            `Error saving data file to path: ${currentPath}`,
+            "save",
+            currentPath,
+            cause
+          );
+          onError?.(error);
           if (state.current.path === currentPath && state.current.data === currentData) {
             state.current.state = { state: "error", error };
             updateDataFromState();
@@ -140,11 +160,11 @@ function useDataFileCore({
         state.current.state = { state: "saved" };
         updateDataFromState();
       }
-    }).catch((error) => {
+    }).catch((err) => {
       if (state.current.path !== path) {
         return;
       }
-      if (error.code === "ENOENT") {
+      if (err.code === "ENOENT") {
         const initialData = onPathChange === "transfer" && state.current.previousData !== void 0 ? state.current.previousData : defaultValue;
         state.current.data = initialData;
         state.current.lastUpdatedMillis = Date.now();
@@ -158,6 +178,14 @@ function useDataFileCore({
         updateDataFromState();
         return;
       }
+      const error = new ArcaneDataFileError(
+        `Error loading data file at path: ${path}`,
+        "load",
+        path,
+        err
+      );
+      onError?.(error);
+      log?.error(error);
       state.current.state = { state: "error", error };
       updateDataFromState();
     });
@@ -202,17 +230,25 @@ function createDataFileDefinition({
   });
   const useDataFile2 = ({
     path,
-    onPathChange
+    onPathChange,
+    onError
   }) => useDataFileCore({
     schema,
     defaultValue,
     path,
-    onPathChange
+    onPathChange,
+    onError
   });
-  const Provider = ({ path, onPathChange, children }) => {
+  const Provider = ({
+    path,
+    onPathChange,
+    onError,
+    children
+  }) => {
     const { data, updateData, saveData } = useDataFile2({
       path,
-      onPathChange
+      onPathChange,
+      onError
     });
     const providedContext = useMemo(
       () => ({
@@ -237,6 +273,7 @@ function createDataFileDefinition({
   };
 }
 export {
+  ArcaneDataFileError,
   createDataFileDefinition,
   useDataFile,
   useDataFileContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcanejs/react-toolkit",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "private": false,
   "description": "Build web-accessible control interfaces for your long-running Node.js processes",
   "keywords": [