@kellanjs/actioncraft 0.0.2 → 0.2.0

package/dist/utils.js

@@ -1,4 +1,6 @@
-import { ActionCraftError } from "./error.js";
+import { ActioncraftError } from "./classes/error.js";
+import { EXTERNAL_ERROR_TYPES } from "./types/errors.js";
+import { err } from "./types/result.js";
 export function unwrap(resultOrPromise) {
     // Handle Promise case
     if (resultOrPromise instanceof Promise) {
@@ -8,16 +10,18 @@ export function unwrap(resultOrPromise) {
     return _unwrapSync(resultOrPromise);
 }
 /**
- * Synchronously unwraps a result, throwing on error.
+ * Synchronously unwraps a result, throwing on error with embedded action ID.
  */
 function _unwrapSync(result) {
-    // Handle api-style results ({ success: true/false })
+    // Extract action ID from result if present
+    const actionId = "__ac_id" in result ? result.__ac_id : undefined;
+    // Handle api-style results ({ success: true/false }) - includes both ApiResult and StatefulApiResult
     if (typeof result === "object" && result !== null && "success" in result) {
         const apiResult = result;
         if (apiResult.success) {
             return apiResult.data;
         }
-        throw new ActionCraftError(apiResult.error);
+        throw new ActioncraftError(apiResult.error, actionId);
     }
     // Handle functional-style results ({ type: "ok"/"err" })
     if (typeof result === "object" && result !== null && "type" in result) {
@@ -25,13 +29,14 @@ function _unwrapSync(result) {
         if (functionalResult.type === "ok") {
             return functionalResult.value;
         }
-        throw new ActionCraftError(functionalResult.error);
+        throw new ActioncraftError(functionalResult.error, actionId);
     }
-    throw new Error("Invalid result format from ActionCraft action");
+    throw new Error("Invalid result format from Actioncraft action");
 }
 /**
- * Creates a throwable version of an ActionCraft action.
- * The returned function throws on error instead of returning Result objects.
+ * Creates a throwable version of an Actioncraft action.
+ * The returned function throws ActioncraftErrors with automatic action ID verification support.
+ * Errors thrown by this function can be verified with isActioncraftError(error, action).
  */
 export function throwable(action) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -41,4 +46,59 @@ export function throwable(action) {
         return unwrap(result);
     });
 }
+/**
+ * Creates an appropriate initial state for any action based on its configuration.
+ * The initial state uses the action's real ID for consistency with actual results.
+ *
+ * For useActionState actions: returns StatefulApiResult with error and values
+ * For functional format actions: returns Result.err() with error
+ * For regular actions: returns ApiResult with error
+ *
+ * Usage:
+ * - useActionState: const [state, action] = useActionState(myAction, initial(myAction))
+ * - useState: const [state, setState] = useState(initial(myAction))
+ */
+export function initial(action) {
+    const error = {
+        type: EXTERNAL_ERROR_TYPES.INITIAL_STATE,
+        message: "Action has not been executed yet",
+    };
+    // Attempt to read the action ID created during craft()
+    const actionId = 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    action?.__ac_id ?? "unknown";
+    // Attempt to read the Actioncraft config attached during craft()
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cfg = action?.__ac_config;
+    // Functional format -> Result<_, _>
+    if (cfg?.resultFormat === "functional") {
+        return err(error, actionId);
+    }
+    // useActionState enabled -> StatefulApiResult
+    if (cfg?.useActionState) {
+        return {
+            success: false,
+            error,
+            values: undefined,
+            __ac_id: actionId,
+        };
+    }
+    // Default ApiResult shape
+    return {
+        success: false,
+        error,
+        __ac_id: actionId,
+    };
+}
+/**
+ * Utility to extract the action ID from a crafted action.
+ * Useful for debugging and logging purposes.
+ *
+ * @param action - The crafted action
+ * @returns The action ID if available, undefined otherwise
+ */
+export function getActionId(action) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return action.__ac_id;
+}
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAkB9C,MAAM,UAAU,MAAM,CACpB,eAG6D;IAE7D,sBAAsB;IACtB,IAAI,eAAe,YAAY,OAAO,EAAE,CAAC;QACvC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,4BAA4B;IAC5B,OAAO,WAAW,CAAC,eAAe,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAClB,MAAwD;IAExD,qDAAqD;IACrD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;QACzE,MAAM,SAAS,GAAG,MAAkC,CAAC;QACrD,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC,IAAI,CAAC;QACxB,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,yDAAyD;IACzD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QACtE,MAAM,gBAAgB,GAAG,MAA+B,CAAC;QACzD,IAAI,gBAAgB,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACnC,OAAO,gBAAgB,CAAC,KAAK,CAAC;QAChC,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAGvB,MAAe;IACf,8DAA8D;IAC9D,OAAO,CAAC,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;QAC/B,8DAA8D;QAC9D,MAAM,MAAM,GAAG,MAAO,MAAc,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC,CAA6B,CAAC;AACjC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kellanjs/actioncraft",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "Fluent, type-safe builder for Next.js server actions.",
   "keywords": [
     "next.js",
@@ -68,7 +68,7 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.1",
     "vitest": "^3.2.4",
-    "zod": "^3.25.74",
-    "zod-form-data": "^3.0.0"
+    "zod": "^4.1.5",
+    "zod-form-data": "^3.0.1"
   }
 }