@izara_frontend/service-schemas 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,133 @@
+# @izara_frontend/service-schemas
+
+Quick guide — initialize the schema tools and use the provided hooks (e.g. `getObjectLinks`).
+
+**Requirement**
+  - react:  "^18.3.1",
+  - react-dom: "^18.3.1"
+
+**Purpose**
+- This package exports helpers and hook-like functions to fetch and work with service object schemas (links, object schemas, validators, etc.).
+- It expects you to initialize a small runtime integration once (injecting reducers and the posts API) and then use the exported functions inside components or utility modules.
+
+**Install**
+- This package is intended to be consumed from your monorepo packages. Example (if published):
+
+```bash
+npm install @izara_frontend/service-schemas
+```
+
+**Initialization (required once, before using hooks)**
+- Call `initGetSchemaTools` in a parent component or application bootstrap code. The `initGetSchemaTools` call persists across components and only needs to be done once per app lifetime.
+
+Example (typical place: app entry or parent module):
+
+```js
+import { initGetSchemaTools } from "@izara_frontend/service-schemas";
+
+// These values come from your app: an injection helper, the Redux store, and your RTK Query postsApi factory.
+initGetSchemaTools({
+  injectReducer: injectReducerV2,
+  store,
+  createPostsApi: createPostsApiV2
+});
+```
+
+- `injectReducer` should be a function that knows how to inject a reducer into your store (your app's implementation). If you use a helper `injectReducerV2` in your repo, pass it.
+- `store` is the Redux store instance used by your app.
+- `createPostsApi` is the factory that creates the postsApi used by the package; pass your app variant if you have one.
+
+**Using exported helpers (example: `getObjectLinks`)**
+- Each helper follows a small pattern: when called it returns a tuple and a callable object you can use directly.
+
+Typical usage inside a component:
+
+```js
+import React, { useEffect } from 'react';
+import { getObjectLinks } from '@izara_frontend/service-schemas';
+
+export default function MyComponent() {
+  // call at top-level of component
+  const [objLinksResults, getObjectLinksFn, objLinksOption] = getObjectLinks();
+
+  // objLinksResults and objLinksOption are React state objects managed by the hook
+  useEffect(() => {
+    async function load() {
+      // "normal" call: the helper will update objLinksResults and objLinksOption state
+      const [schema, errorsFound] = await getObjectLinksFn({ serviceTag: 'xx', objectType: 'xx' });
+      // schema and errorsFound are the results of this call
+    }
+    load();
+  }, []);
+
+  return <div>...render using objLinksResults...</div>;
+}
+```
+
+Direct-trigger usage via `.initiate` (RTK-style)
+
+- Some helper callables expose an `.initiate(params)` method. This returns a promise with the response and does NOT automatically push results into the returned React state tuple — it gives the result directly.
+
+```js
+// using initiate to get the value directly
+const [schema, errorsFound] = await getObjectLinksFn().initiate({ serviceTag: 'xx', objectType: 'xx' });
+// This returns the fetched value immediately; it does not mutate objLinksResults / objLinksOption state.
+```
+
+**Difference between "normal" and `.initiate()`**
+- Normal call (calling `getObjectLinksFn(params)`):
+  - Updates the returned `objLinksResults` and `objLinksOption` React state (so components re-render and you can read them directly).
+  - Useful when you want to keep the result in component state and react to changes.
+- `.initiate(params)` call:
+  - Returns the response directly (a promise). It is useful when you want a one-off result (for example inside an async handler) and don't need the returned hook state to update.
+  - That call is usually useful for programmatic flows or server-side usage where you only need the returned value.
+
+**Return shapes / tuple explained**
+- The pattern is typically:
+
+```js
+const [resultsState, actionFn, optionsState] = someGetFunction();
+```
+
+- `resultsState` — React state managed by the helper: contains last response (schema, data) and flags.
+- `actionFn` — a callable function you can call with params to fetch. Also may expose `.initiate()` for direct returns.
+- `optionsState` — optional object with metadata such as isLoading, isError, status, etc.
+
+**Examples**
+- Normal usage (keeps result in state):
+
+```js
+const [objLinksResults, getObjectLinksFn, objLinksOption] = getObjectLinks();
+
+useEffect(() => {
+  getObjectLinksFn({ serviceTag: 'shop', objectType: 'product' });
+}, []);
+
+// read results from objLinksResults
+```
+
+- One-off result via `.initiate` (direct):
+
+```js
+const [, getObjectLinksFn] = getObjectLinks();
+
+async function fetchNow() {
+  const [schema, errorsFound] = await getObjectLinksFn().initiate({ serviceTag: 'shop', objectType: 'product' });
+  // use schema directly
+}
+```
+
+**Notes & best practices**
+- Initialize `initGetSchemaTools` before using any of the exported helpers. A safe place is your app root or a parent component that mounts early.
+- Place the `getObjectX` call (the `someGetFunction()` call) at top-level of your React component (not inside conditionals) so hooks rules are respected.
+- Many helpers accept different params — check the helper signature you use. The package provides multiple fetch helpers (links, object schema, validators, etc.) each with their own param set.
+- `.initiate()` will not update the hook-managed state; use it when you need a single direct result.
+
+**Troubleshooting**
+- If results are not appearing in `resultsState` after a normal call:
+  - Ensure `initGetSchemaTools` was called with the correct `store` and `createPostsApi`.
+  - Ensure the helper is used inside a component where the hook can run.
+- If you get multiple or stale values, check cache keys and parameters passed to the helper.
+
+
+---

package/index.js

@@ -6,6 +6,7 @@ export {
   getRequiredOnCreateLinks,
   getRelationshipSchema,
   getObjSchemaWithOutHierarchy,
+  collectObjectSchemaWithHierarchy,
   getObjSchemaWithHierarchy,
   getObjSchemaCombineFieldNames,
   getLinkConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izara_frontend/service-schemas",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "",
   "main": "index.js",
   "scripts": {

package/src/getObjectSchema.js

@@ -819,6 +819,112 @@ export function getObjSchemaWithHierarchy() {
   return [result, run, { errorsFound }];
 }
 
+export function collectObjectSchemaWithHierarchy() {
+  const [, getObjectSchemaWithHierarchyFn] = getObjSchemaWithHierarchy();
+
+  const [result, setResult] = useState(null);
+  const [errorsFound, setErrorsFound] = useState([]);
+
+
+
+  // ref to always read latest result inside async functions (avoids stale closures)
+  const resultRef = useRef(result);
+  useEffect(() => { resultRef.current = result; }, [result]);
+
+  // core executor that does the actual work and optionally updates hook state
+  const execute = useCallback(async (objType, { updateState = true } = {}) => {
+
+    async function collectObjectSchemaWithHierarchyMain(objType) {
+
+      // validate objType (some validators throw, some return errors)
+      try {
+        validateObjType(objType);
+      } catch (err) {
+        return [null, [err.message]];
+      }
+
+      // compute mainObjTypeConcat and validate
+      const [mainObjTypeConcat, mainObjTypeErrors] = createObjTypeConcat(objType);
+      if (mainObjTypeErrors && mainObjTypeErrors.length) {
+        return [null, mainObjTypeErrors];
+      }
+
+      // short-circuit: if updateState and we already have this objType in result, return cached value
+      if (updateState && resultRef.current && resultRef.current.hasOwnProperty(mainObjTypeConcat)) {
+        return [{ [mainObjTypeConcat]: resultRef.current[mainObjTypeConcat] }, []];
+      }
+
+
+      const [objSchema, getObjSchemaErrors] = await getObjectSchemaWithHierarchyFn().initiate(objType);
+
+
+      return [objSchema, getObjSchemaErrors];
+    }
+
+    try {
+
+
+      const [returnSchema, errorsFound] = await collectObjectSchemaWithHierarchyMain(objType);
+      // const schema = returnSchema ? { [createObjTypeConcat(objType)]: schema } : null;
+
+      let schema = null;
+      if (returnSchema) {
+        schema = { [createObjTypeConcat(objType)[0]]: returnSchema }
+      }
+
+      if (updateState) {
+        if (errorsFound && errorsFound.length) {
+          setErrorsFound(errorsFound);
+          setResult(null);
+        } else {
+          const [currentObjTypeConcat] = createObjTypeConcat(objType);
+          setResult(prev => {
+            // nothing to add
+            if (!schema || !Object.keys(schema).length) return prev;
+
+            // first-time fill
+            if (!prev) return schema;
+
+            // already have this objType => no update
+            if (prev.hasOwnProperty(currentObjTypeConcat)) return prev;
+            // merge but return a NEW object to trigger React update (do not mutate prev)
+            return { ...prev, ...schema };
+          });
+
+          setErrorsFound([]);
+        }
+      }
+
+      return [schema, errorsFound];
+    } catch (err) {
+      const msg = err?.message || String(err);
+      if (updateState) {
+        setErrorsFound([msg]);
+        setResult(null);
+      }
+      return [null, [msg]];
+    }
+  }, [getObjectSchemaWithHierarchyFn]);
+
+
+  // run can be used two ways:
+  // 1) run(objType) -> updates hook state and returns Promise<[collected, errors]>
+  // 2) run().initiate(objType) -> does NOT touch hook state, returns Promise<[collected, errors]>
+  const run = useCallback((objType) => {
+    if (typeof objType === "undefined") {
+      return {
+        initiate: (objType) => execute(objType, { updateState: false }),
+        clear: () => { setResult(null); setErrorsFound([]); }
+      };
+    }
+    // direct call: update state
+    return execute(objType, { updateState: true });
+  }, [execute]);
+
+  return [result, run, { errorsFound }];
+}
+
+
 export function getObjSchemaCombineFieldNames() {
 
   const [, getObjSchemaWithHierarchyFn] = getObjSchemaWithHierarchy();