@arcanejs/react-toolkit 0.1.5 → 0.3.0

package/dist/data.d.mts

@@ -0,0 +1,96 @@
+import { ReactNode, FC, Context } from 'react';
+import { ZodType } from 'zod';
+
+type WithPathChange = {
+    /**
+     * When the file path changes and the file does not yet exist,
+     * should the previous data be stored in the new file
+     * or should the new file be reset to the default value?
+     *
+     * @default 'defaultValue'
+     */
+    onPathChange?: 'transfer' | 'defaultValue';
+};
+type DataFileUsage = WithPathChange & {
+    /**
+     * The path to where the JSON data should be stored,
+     * this will be relative to the current working directory.
+     */
+    path: string;
+};
+type ProviderProps = DataFileUsage & {
+    children: ReactNode;
+};
+type DataFileUpdater<T> = (update: (current: T) => T) => void;
+type DataFileContext<T> = {
+    data: T;
+    updateData: DataFileUpdater<T>;
+    /**
+     * Can be called to force an attempt to re-save the data to disk
+     */
+    saveData: () => void;
+    /**
+     * If an error has ocurred in the last operation (e.g. load or save,
+     * then this will be set to that error).
+     *
+     * Can be used for example to re-prompt users to save data.
+     */
+    error: unknown;
+};
+type DataFileDefinition<T> = {
+    Provider: FC<ProviderProps>;
+    context: Context<DataFileContext<T>>;
+    useDataFile: (props: DataFileUsage) => DataFileCore<T>;
+};
+declare function useDataFileData<T>(dataFile: DataFileDefinition<T>): T;
+declare function useDataFileUpdater<T>(dataFile: DataFileDefinition<T>): DataFileUpdater<T>;
+/**
+ * Convenience hook to use the internal data-file context hook
+ */
+declare function useDataFileContext<T>(dataFile: DataFileDefinition<T>): DataFileContext<T>;
+/**
+ * Convenience hook to use the internal data-file definition hook
+ * in a more react-like manner.
+ */
+declare function useDataFile<T>(dataFile: DataFileDefinition<T>, usage: DataFileUsage): DataFileCore<T>;
+type DataState<T> = {
+    status: 'loading';
+    /**
+     * The data is not yet loaded, so this will be undefined,
+     * but it's listed here as a property so that the data property can be
+     * directly used without a type-guard that uses `state`.
+     *
+     * This should hopefully also avoid situations where users may check for
+     * `state === 'ready'` instead of `state !== 'loading'`,
+     * and accidentally avoid displaying data that's available but unsaved.
+     */
+    data: undefined;
+} | {
+    status: 'error';
+    data: T | undefined;
+    error: unknown;
+} | {
+    status: 'ready';
+    data: T;
+};
+type UseDataFileCoreProps<T> = WithPathChange & {
+    schema: ZodType<T>;
+    defaultValue: T;
+    path: string;
+};
+type DataFileCore<T> = {
+    data: DataState<T>;
+    updateData: DataFileUpdater<T>;
+    saveData: () => void;
+};
+/**
+ * Primary hook for & logic for using data files.
+ */
+declare function useDataFileCore<T>({ schema, defaultValue, path, onPathChange, }: UseDataFileCoreProps<T>): DataFileCore<T>;
+type CreateDataFileDefinitionProps<T> = {
+    schema: ZodType<T>;
+    defaultValue: T;
+};
+declare function createDataFileDefinition<T>({ schema, defaultValue, }: CreateDataFileDefinitionProps<T>): DataFileDefinition<T>;
+
+export { type CreateDataFileDefinitionProps, type DataFileContext, type DataFileCore, type DataFileDefinition, type DataFileUpdater, type DataState, type ProviderProps, type UseDataFileCoreProps, createDataFileDefinition, useDataFile, useDataFileContext, useDataFileCore, useDataFileData, useDataFileUpdater };

package/dist/data.d.ts

@@ -0,0 +1,96 @@
+import { ReactNode, FC, Context } from 'react';
+import { ZodType } from 'zod';
+
+type WithPathChange = {
+    /**
+     * When the file path changes and the file does not yet exist,
+     * should the previous data be stored in the new file
+     * or should the new file be reset to the default value?
+     *
+     * @default 'defaultValue'
+     */
+    onPathChange?: 'transfer' | 'defaultValue';
+};
+type DataFileUsage = WithPathChange & {
+    /**
+     * The path to where the JSON data should be stored,
+     * this will be relative to the current working directory.
+     */
+    path: string;
+};
+type ProviderProps = DataFileUsage & {
+    children: ReactNode;
+};
+type DataFileUpdater<T> = (update: (current: T) => T) => void;
+type DataFileContext<T> = {
+    data: T;
+    updateData: DataFileUpdater<T>;
+    /**
+     * Can be called to force an attempt to re-save the data to disk
+     */
+    saveData: () => void;
+    /**
+     * If an error has ocurred in the last operation (e.g. load or save,
+     * then this will be set to that error).
+     *
+     * Can be used for example to re-prompt users to save data.
+     */
+    error: unknown;
+};
+type DataFileDefinition<T> = {
+    Provider: FC<ProviderProps>;
+    context: Context<DataFileContext<T>>;
+    useDataFile: (props: DataFileUsage) => DataFileCore<T>;
+};
+declare function useDataFileData<T>(dataFile: DataFileDefinition<T>): T;
+declare function useDataFileUpdater<T>(dataFile: DataFileDefinition<T>): DataFileUpdater<T>;
+/**
+ * Convenience hook to use the internal data-file context hook
+ */
+declare function useDataFileContext<T>(dataFile: DataFileDefinition<T>): DataFileContext<T>;
+/**
+ * Convenience hook to use the internal data-file definition hook
+ * in a more react-like manner.
+ */
+declare function useDataFile<T>(dataFile: DataFileDefinition<T>, usage: DataFileUsage): DataFileCore<T>;
+type DataState<T> = {
+    status: 'loading';
+    /**
+     * The data is not yet loaded, so this will be undefined,
+     * but it's listed here as a property so that the data property can be
+     * directly used without a type-guard that uses `state`.
+     *
+     * This should hopefully also avoid situations where users may check for
+     * `state === 'ready'` instead of `state !== 'loading'`,
+     * and accidentally avoid displaying data that's available but unsaved.
+     */
+    data: undefined;
+} | {
+    status: 'error';
+    data: T | undefined;
+    error: unknown;
+} | {
+    status: 'ready';
+    data: T;
+};
+type UseDataFileCoreProps<T> = WithPathChange & {
+    schema: ZodType<T>;
+    defaultValue: T;
+    path: string;
+};
+type DataFileCore<T> = {
+    data: DataState<T>;
+    updateData: DataFileUpdater<T>;
+    saveData: () => void;
+};
+/**
+ * Primary hook for & logic for using data files.
+ */
+declare function useDataFileCore<T>({ schema, defaultValue, path, onPathChange, }: UseDataFileCoreProps<T>): DataFileCore<T>;
+type CreateDataFileDefinitionProps<T> = {
+    schema: ZodType<T>;
+    defaultValue: T;
+};
+declare function createDataFileDefinition<T>({ schema, defaultValue, }: CreateDataFileDefinitionProps<T>): DataFileDefinition<T>;
+
+export { type CreateDataFileDefinitionProps, type DataFileContext, type DataFileCore, type DataFileDefinition, type DataFileUpdater, type DataState, type ProviderProps, type UseDataFileCoreProps, createDataFileDefinition, useDataFile, useDataFileContext, useDataFileCore, useDataFileData, useDataFileUpdater };

package/dist/data.js

@@ -0,0 +1,248 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/data.tsx
+var data_exports = {};
+__export(data_exports, {
+  createDataFileDefinition: () => createDataFileDefinition,
+  useDataFile: () => useDataFile,
+  useDataFileContext: () => useDataFileContext,
+  useDataFileCore: () => useDataFileCore,
+  useDataFileData: () => useDataFileData,
+  useDataFileUpdater: () => useDataFileUpdater
+});
+module.exports = __toCommonJS(data_exports);
+var import_fs = require("fs");
+var import_react = require("react");
+var import_lodash = require("lodash");
+var import_path = require("path");
+var import_jsx_runtime = require("react/jsx-runtime");
+function useDataFileData(dataFile) {
+  return (0, import_react.useContext)(dataFile.context).data;
+}
+function useDataFileUpdater(dataFile) {
+  return (0, import_react.useContext)(dataFile.context).updateData;
+}
+function useDataFileContext(dataFile) {
+  return (0, import_react.useContext)(dataFile.context);
+}
+function useDataFile(dataFile, usage) {
+  return dataFile.useDataFile(usage);
+}
+function useDataFileCore({
+  schema,
+  defaultValue,
+  path,
+  onPathChange = "defaultValue"
+}) {
+  const state = (0, import_react.useRef)({
+    initialized: false,
+    path: null,
+    data: void 0,
+    previousData: void 0,
+    state: {
+      state: "saved"
+    }
+  });
+  (0, import_react.useEffect)(() => {
+    if (!state.current.initialized) {
+      state.current.initialized = true;
+    } else {
+      throw new Error(
+        "Cannot change schema or defaultValue after initialization"
+      );
+    }
+  }, [schema, defaultValue]);
+  const [data, setData] = (0, import_react.useState)({
+    status: "loading",
+    data: void 0
+  });
+  const updateDataFromState = (0, import_react.useMemo)(
+    () => () => {
+      const data2 = state.current.data;
+      if (state.current.state.state === "error") {
+        setData({
+          status: "error",
+          error: state.current.state.error,
+          data: data2
+        });
+        return;
+      }
+      if (data2 === void 0) {
+        setData({
+          status: "loading",
+          data: void 0
+        });
+        return;
+      }
+      setData({
+        status: "ready",
+        data: data2
+      });
+    },
+    []
+  );
+  const saveData = (0, import_react.useMemo)(
+    () => (0, import_lodash.throttle)(
+      async () => {
+        if (state.current.state.state === "saved") {
+          return;
+        }
+        const currentPath = state.current.path;
+        const currentData = state.current.data;
+        if (!currentPath || currentData === void 0) {
+          return;
+        }
+        try {
+          const json = JSON.stringify(currentData, null, 2);
+          await import_fs.promises.mkdir((0, import_path.dirname)(currentPath), { recursive: true });
+          await import_fs.promises.writeFile(currentPath, json, "utf8");
+          if (state.current.path === currentPath && state.current.data === currentData) {
+            state.current.state = { state: "saved" };
+          }
+        } catch (error) {
+          if (state.current.path === currentPath && state.current.data === currentData) {
+            state.current.state = { state: "error", error };
+            updateDataFromState();
+          }
+        }
+      },
+      500,
+      {
+        // Write leading so that we always write to disk quickly when
+        // only single things have changed
+        leading: true,
+        // Trailing is important otherwise we may lose data
+        trailing: true
+      }
+    ),
+    []
+  );
+  (0, import_react.useEffect)(() => {
+    state.current = {
+      ...state.current,
+      path,
+      data: void 0,
+      previousData: state.current.data ?? state.current.previousData,
+      state: {
+        state: "saved"
+      }
+    };
+    import_fs.promises.readFile(path, "utf8").then((data2) => {
+      const parsedData = schema.parse(JSON.parse(data2));
+      if (state.current.path === path) {
+        state.current.data = parsedData;
+        state.current.state = { state: "saved" };
+        updateDataFromState();
+      }
+    }).catch((error) => {
+      if (state.current.path !== path) {
+        return;
+      }
+      if (error.code === "ENOENT") {
+        console.log("Creating new file");
+        const initialData = onPathChange === "transfer" && state.current.previousData !== void 0 ? state.current.previousData : defaultValue;
+        state.current.data = initialData;
+        state.current.state = { state: "dirty" };
+        saveData();
+        updateDataFromState();
+        return;
+      }
+      state.current.state = { state: "error", error };
+      updateDataFromState();
+    });
+  }, [path, onPathChange]);
+  const updateData = (0, import_react.useMemo)(
+    () => (update) => {
+      if (state.current.path !== path) {
+        return;
+      }
+      if (state.current.data === void 0) {
+        throw new Error("Attempt to update data before it has been loaded");
+      }
+      state.current.data = update(state.current.data);
+      state.current.state = { state: "dirty" };
+      saveData();
+      updateDataFromState();
+    },
+    [path]
+  );
+  return {
+    data,
+    updateData,
+    saveData
+  };
+}
+function createDataFileDefinition({
+  schema,
+  defaultValue
+}) {
+  const context = (0, import_react.createContext)({
+    data: defaultValue,
+    updateData: () => {
+      throw new Error("Data file provider not used");
+    },
+    saveData: () => {
+      throw new Error("Data file provider not used");
+    },
+    error: void 0
+  });
+  const useDataFile2 = ({
+    path,
+    onPathChange
+  }) => useDataFileCore({
+    schema,
+    defaultValue,
+    path,
+    onPathChange
+  });
+  const Provider = ({ path, onPathChange, children }) => {
+    const { data, updateData, saveData } = useDataFile2({
+      path,
+      onPathChange
+    });
+    const providedContext = (0, import_react.useMemo)(
+      () => ({
+        data: data.status !== "loading" && data.data !== void 0 ? data.data : defaultValue,
+        updateData,
+        saveData,
+        error: data.status === "error" ? data.error : void 0
+      }),
+      [data, updateData]
+    );
+    if (data.status === "loading") {
+      return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: "Loading..." });
+    }
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(context.Provider, { value: providedContext, children });
+  };
+  return {
+    Provider,
+    context,
+    useDataFile: useDataFile2
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDataFileDefinition,
+  useDataFile,
+  useDataFileContext,
+  useDataFileCore,
+  useDataFileData,
+  useDataFileUpdater
+});

package/dist/data.mjs

@@ -0,0 +1,225 @@
+// src/data.tsx
+import { promises as fs } from "fs";
+import {
+  useMemo,
+  useContext,
+  createContext,
+  useState,
+  useEffect,
+  useRef
+} from "react";
+import { throttle } from "lodash";
+import { dirname } from "path";
+import { Fragment, jsx } from "react/jsx-runtime";
+function useDataFileData(dataFile) {
+  return useContext(dataFile.context).data;
+}
+function useDataFileUpdater(dataFile) {
+  return useContext(dataFile.context).updateData;
+}
+function useDataFileContext(dataFile) {
+  return useContext(dataFile.context);
+}
+function useDataFile(dataFile, usage) {
+  return dataFile.useDataFile(usage);
+}
+function useDataFileCore({
+  schema,
+  defaultValue,
+  path,
+  onPathChange = "defaultValue"
+}) {
+  const state = useRef({
+    initialized: false,
+    path: null,
+    data: void 0,
+    previousData: void 0,
+    state: {
+      state: "saved"
+    }
+  });
+  useEffect(() => {
+    if (!state.current.initialized) {
+      state.current.initialized = true;
+    } else {
+      throw new Error(
+        "Cannot change schema or defaultValue after initialization"
+      );
+    }
+  }, [schema, defaultValue]);
+  const [data, setData] = useState({
+    status: "loading",
+    data: void 0
+  });
+  const updateDataFromState = useMemo(
+    () => () => {
+      const data2 = state.current.data;
+      if (state.current.state.state === "error") {
+        setData({
+          status: "error",
+          error: state.current.state.error,
+          data: data2
+        });
+        return;
+      }
+      if (data2 === void 0) {
+        setData({
+          status: "loading",
+          data: void 0
+        });
+        return;
+      }
+      setData({
+        status: "ready",
+        data: data2
+      });
+    },
+    []
+  );
+  const saveData = useMemo(
+    () => throttle(
+      async () => {
+        if (state.current.state.state === "saved") {
+          return;
+        }
+        const currentPath = state.current.path;
+        const currentData = state.current.data;
+        if (!currentPath || currentData === void 0) {
+          return;
+        }
+        try {
+          const json = JSON.stringify(currentData, null, 2);
+          await fs.mkdir(dirname(currentPath), { recursive: true });
+          await fs.writeFile(currentPath, json, "utf8");
+          if (state.current.path === currentPath && state.current.data === currentData) {
+            state.current.state = { state: "saved" };
+          }
+        } catch (error) {
+          if (state.current.path === currentPath && state.current.data === currentData) {
+            state.current.state = { state: "error", error };
+            updateDataFromState();
+          }
+        }
+      },
+      500,
+      {
+        // Write leading so that we always write to disk quickly when
+        // only single things have changed
+        leading: true,
+        // Trailing is important otherwise we may lose data
+        trailing: true
+      }
+    ),
+    []
+  );
+  useEffect(() => {
+    state.current = {
+      ...state.current,
+      path,
+      data: void 0,
+      previousData: state.current.data ?? state.current.previousData,
+      state: {
+        state: "saved"
+      }
+    };
+    fs.readFile(path, "utf8").then((data2) => {
+      const parsedData = schema.parse(JSON.parse(data2));
+      if (state.current.path === path) {
+        state.current.data = parsedData;
+        state.current.state = { state: "saved" };
+        updateDataFromState();
+      }
+    }).catch((error) => {
+      if (state.current.path !== path) {
+        return;
+      }
+      if (error.code === "ENOENT") {
+        console.log("Creating new file");
+        const initialData = onPathChange === "transfer" && state.current.previousData !== void 0 ? state.current.previousData : defaultValue;
+        state.current.data = initialData;
+        state.current.state = { state: "dirty" };
+        saveData();
+        updateDataFromState();
+        return;
+      }
+      state.current.state = { state: "error", error };
+      updateDataFromState();
+    });
+  }, [path, onPathChange]);
+  const updateData = useMemo(
+    () => (update) => {
+      if (state.current.path !== path) {
+        return;
+      }
+      if (state.current.data === void 0) {
+        throw new Error("Attempt to update data before it has been loaded");
+      }
+      state.current.data = update(state.current.data);
+      state.current.state = { state: "dirty" };
+      saveData();
+      updateDataFromState();
+    },
+    [path]
+  );
+  return {
+    data,
+    updateData,
+    saveData
+  };
+}
+function createDataFileDefinition({
+  schema,
+  defaultValue
+}) {
+  const context = createContext({
+    data: defaultValue,
+    updateData: () => {
+      throw new Error("Data file provider not used");
+    },
+    saveData: () => {
+      throw new Error("Data file provider not used");
+    },
+    error: void 0
+  });
+  const useDataFile2 = ({
+    path,
+    onPathChange
+  }) => useDataFileCore({
+    schema,
+    defaultValue,
+    path,
+    onPathChange
+  });
+  const Provider = ({ path, onPathChange, children }) => {
+    const { data, updateData, saveData } = useDataFile2({
+      path,
+      onPathChange
+    });
+    const providedContext = useMemo(
+      () => ({
+        data: data.status !== "loading" && data.data !== void 0 ? data.data : defaultValue,
+        updateData,
+        saveData,
+        error: data.status === "error" ? data.error : void 0
+      }),
+      [data, updateData]
+    );
+    if (data.status === "loading") {
+      return /* @__PURE__ */ jsx(Fragment, { children: "Loading..." });
+    }
+    return /* @__PURE__ */ jsx(context.Provider, { value: providedContext, children });
+  };
+  return {
+    Provider,
+    context,
+    useDataFile: useDataFile2
+  };
+}
+export {
+  createDataFileDefinition,
+  useDataFile,
+  useDataFileContext,
+  useDataFileCore,
+  useDataFileData,
+  useDataFileUpdater
+};