chore: most of NextSteps - done. Next is better error narrowing

Author: tunnckoCore

src-v4/NEXT_STEPS.md

@@ -4,15 +4,19 @@
 
 Updated to specify deep cloning for context merging (not just spreading).
 
-### 1. Add `.callable(context?: TContext)` Method
+DONE
+### 1. Add `.callable(context?: TContext)` Method 
+DONE
 - **Goal**: Separate procedure definition from execution; `.handler` defines the handler and returns the builder instance, while `.callable` returns the actual callable procedure with optional context.
 - **Implementation**:
   - Add `.callable<TContext>(context?: TContext)` method to the builder.
   - It should finalize the builder and return a callable function (the "procedure") that accepts procedure args and executes the wrapped logic.
   - Ensure context is passed to the procedure for use in `options.context`.
   - This is the first step to establish the builder pattern clearly.
 
+DONE
 ### 2. Context Support with `.context<TInitialContext>(initialContext?)`
+DONE
 - **Goal**: Allow defining an initial context type and value for `options.context` via a method, which can be merged with context passed to `.callable`.
 - **Implementation**:
   - Add `.context<TInitialContext>(initialContext?: TInitialContext)` method to the builder, storing the type and initial value.
@@ -21,23 +25,29 @@ Updated to specify deep cloning for context merging (not just spreading).
   - Pass the merged context to `options.context` in the procedure.
   - Ensure type inference propagates to `ProcedureOptions`.
 
-### 3. Options Parameter in Handlers
+DONE
+### 3. Options Parameter in Handlers 
+DONE
 - **Goal**: Always pass `options: { errors: ErrorHelpers, context: Context }` as the first param to handlers, where `errors` are helpers that throw structured objects (not Errors).
 - **Implementation**:
   - Define `ProcedureOptions<TContext, TErrors>` as `{ errors: Record<keyof TErrors, (data: any) => { type: keyof TErrors, ...data }>, context: TContext }`.
   - Use `createErrorHelpers` to generate `errors` object; each helper validates against the schema and throws `{ type: key, ...validatedData }`.
   - Ensure `type` is inferred from the key and required in schemas (e.g., `type: z.literal('NOT_FOUND')`).
   - Pass `options` as the first arg to `fn(options, ...finalArgs)`.
 
+DONE
 ### 4. Support for Output Schema with `.output`
+DONE
 - **Goal**: Add `.output<T extends AnySchema>(schema: T)` to validate/transform handler return values.
 - **Implementation**:
   - Add `.output<T>(schema: T)` method, storing `TOutputSchema`.
   - In `wrapped`, after handler call, validate the result against `TOutputSchema` using `schema['~standard'].validate`.
   - If async, handle with `.then()`; on failure, treat as error (via `createResult`).
   - Update generics: `Procedure` should reflect output types.
 
+DONE
 ### 5. Handle Async Validation (schema.validate can return Promise)
+DONE
 - **Goal**: Support both sync and async validation at the type level, with runtime handling via `instanceof Promise` checks and `.then()` chains (no `async/await`).
 - **Implementation**:
   - Introduce `type IsPromise<T> = T extends Promise<any> ? true : false;`.
@@ -46,7 +56,9 @@ Updated to specify deep cloning for context merging (not just spreading).
   - If validation is async, the overall return becomes a Promise. Update return types to `ReturnType<TFn> | Promise<ReturnType<TFn>>`.
   - Handle errors in `.then()` chains by rejecting or wrapping in results.
 
+DONE
 ### 6. Add createResult Utility for Never-Throwing Functions
+DONE
 - **Goal**: Implement `createResult` to return `{ data, error, isTypedError }` and `[data, error, isTypedError]` patterns, ensuring handlers never throw by catching all errors.
 - **Implementation**:
   - Use the provided `createResult(data: any, error: any, isTypedError: boolean)` function, which returns an array with object properties.
@@ -55,7 +67,9 @@ Updated to specify deep cloning for context merging (not just spreading).
   - Support both sync and async contexts; if handler returns a Promise, resolve it before creating the result.
   - Ensure type safety: generics should reflect the result structure.
 
+DONE
 ### 7. Support Sync and Async Handlers
+DONE
 - **Goal**: Allow handlers to be sync or async, detected via generics, and handle with `instanceof Promise` and `.then()` chains (no `async/await`).
 - **Implementation**:
   - Update the `handler` method signature with generics for async detection (reference example: use something like `TIsAsync extends boolean = IsPromise<TReturn>` to infer async behavior).
@@ -64,7 +78,9 @@ Updated to specify deep cloning for context merging (not just spreading).
   - Ensure the final return is a Promise if `TIsAsync` is true.
   - Update types: `Procedure` should have a generic for async, affecting return types.
 
+DONE
 ### 8. Careful Argument Handling (Procedure Args vs. Handler Args)
+DONE
 - **Goal**: Clearly distinguish "procedure args" (inputs to the final callable) from "handler args" (passed to `.handler`), ensuring handler args are based on schema output after defaults, with proper sync/async generic handling.
 - **Implementation**:
   - **Procedure Args**: The inputs to the callable (e.g., `proc("Alice")`); validated against `TInputSchema`.
@@ -73,14 +89,21 @@ Updated to specify deep cloning for context merging (not just spreading).
   - Generics: Define `THandlerArgs` as the spread of output types; ensure `TIsAsync` propagates to avoid type mismatches.
   - Handle edge cases: empty args, single args, tuple defaults.
 
+DONE
 ### 9. Error Map Support with `.errors(errorMap)`
+DONE
 - **Goal**: Support `.errors<T extends Record<string, AnySchema>>(errorMap: T)` to define typed error schemas.
 - **Implementation**:
   - Add `.errors<T>(map: T)` method, storing the map.
   - Use `createErrorHelpers(map, isAsync)` to generate helpers; enforce schemas include `type: z.literal(key)`.
   - Update builder generics for `TErrors = T`.
   - Integrate with `options.errors`; ensure helpers throw validated objects.
 
+TODO - BETTER ERROR NARROWING - when `.errors()` is called, switch to have internal typed UNKNOWN_ERROR
+TODO - BETTER ERROR NARROWING - when `.errors()` is called, switch to have internal typed UNKNOWN_ERROR
+TODO - BETTER ERROR NARROWING - when `.errors()` is called, 
+        switch to have internal typed UNKNOWN_ERROR instead of ZagoraError
+
 ### 10. Update createResult for isTypedError
 - **Goal**: Enhance `createResult` to include `isTypedError` for guarding typed errors, with potential for `isValidationError` later.
 - **Implementation**:

src-v4/ss-valibot.ts

@@ -1,35 +1,37 @@
 import * as v from "valibot";
-import { builder } from "./sscore";
+import { zagora } from "./sscore";
 
 // ============================================================================
 // TESTS
 // ============================================================================
 
 // Test 1: Tuple with defaults
-const proc1 = builder()
+const proc1 = zagora()
   .input(v.tuple([v.string(), v.optional(v.number(), 42)]))
-  .handler((name, age) => ({
+  .handler((options, name, age) => ({
     // passing!
     // name: string
     // age: number - must be, because it's defaulted to 42
     message: `${name} is ${age}`,
-  }));
+  }))
+  .callable();
 
 console.log("Test 1a:", proc1("Alice"));
 console.log("Test 1b:", proc1("Bob", 30));
 
 // Test 1b: Tuple with default + optional
-const proc1b = builder()
+const proc1b = zagora()
   .input(
     v.tuple([v.string(), v.optional(v.number(), 42), v.optional(v.boolean())]),
   )
-  .handler((name, age, verified) => ({
+  .handler((options, name, age, verified) => ({
     // passing!
     // name: string
     // age: number - must be, because it's defaulted to 42
     // verified: boolean | undefined - because it's optional
     message: `${name} is ${age}, verified: ${verified ?? false}`,
-  }));
+  }))
+  .callable();
 
 // should pass because verified is optional
 // and because age is defaulted to 42
@@ -40,28 +42,30 @@ console.log("Test 1b2:", proc1b("Bob", 30));
 console.log("Test 1b3:", proc1b("Carol", 25, true));
 
 // Test 2: Primitive input
-const proc2 = builder()
+const proc2 = zagora()
   .input(v.string())
-  .handler((name) => {
+  .handler((options, name) => {
     // passing!
     // name: string
     return `Hello ${name}!`;
-  });
+  })
+  .callable();
 
 console.log("Test 2:", proc2("World"));
 
 // Test 3: Object input
-const proc3 = builder()
+const proc3 = zagora()
   .input(v.object({ x: v.number(), y: v.optional(v.number(), 2) }))
-  .handler((input) => {
+  .handler((options, input) => {
     // input: { x: number, y: number } - because y is defaulted to 2
     return input.x + input.y;
-  });
+  })
+  .callable();
 
 console.log("Test 3:", proc3({ x: 5, y: 3 }));
 
 // Test 4: Object with defaults and optionals
-const proc4 = builder()
+const proc4 = zagora()
   .input(
     v.tuple([
       v.string(),
@@ -72,11 +76,12 @@ const proc4 = builder()
       }),
     ]),
   )
-  .handler((name, config) => ({
+  .handler((options, name, config) => ({
     // passing!
     // config: { user: string, role: string, paid: boolean | undefined }
     result: `${name}: role=${config.role}, paid=${config.paid ?? false}`,
-  }));
+  }))
+  .callable();
 
 // SHOULD NOT REQUIRE `role` to be passed because it has a default value!
 console.log("Test 4a:", proc4("Alice", { user: "alice" }));

src-v4/ss-zod.ts

@@ -1,33 +1,36 @@
 import z from "zod";
-import { builder } from "./sscore";
+import { zagora } from "./sscore";
 
 // ============================================================================
 // TESTS
 // ============================================================================
 
 // Test 1: Tuple with defaults
-const proc1 = builder()
+const proc1 = zagora()
+  .context<{ foo: string }>()
   .input(z.tuple([z.string(), z.number().default(42)]))
-  .handler((name, age) => ({
+  .handler((opts, name, age) => ({
     // passing!
     // name: string
     // age: number - must be, because it's defaulted to 42
     message: `${name} is ${age}`,
-  }));
+  }))
+  .callable({ foo: "bar", sasa: 123 });
 
 console.log("Test 1a:", proc1("Alice"));
 console.log("Test 1b:", proc1("Bob", 30));
 
 // Test 1b: Tuple with default + optional
-const proc1b = builder()
+const proc1b = zagora()
   .input(z.tuple([z.string(), z.number().default(42), z.boolean().optional()]))
-  .handler((name, age, verified) => ({
+  .handler((options, name, age, verified) => ({
     // passing!
     // name: string
     // age: number - must be, because it's defaulted to 42
     // verified: boolean | undefined - because it's optional
     message: `${name} is ${age}, verified: ${verified ?? false}`,
-  }));
+  }))
+  .callable();
 
 // should pass because verified is optional
 // and because age is defaulted to 42
@@ -38,28 +41,34 @@ console.log("Test 1b2:", proc1b("Bob", 30));
 console.log("Test 1b3:", proc1b("Carol", 25, true));
 
 // Test 2: Primitive input
-const proc2 = builder()
+const proc2 = zagora()
+  .context<{ foo?: string; bar: string }>({ bar: "quxie" })
   .input(z.string())
-  .handler((name) => {
+  .handler((options, name) => {
+    options;
     // passing!
     // name: string
     return `Hello ${name}!`;
-  });
+  })
+  .callable();
 
 console.log("Test 2:", proc2("World"));
 
 // Test 3: Object input
-const proc3 = builder()
+const proc3 = zagora()
   .input(z.object({ x: z.number(), y: z.number().default(2) }))
-  .handler((input) => {
+  .handler((options, input) => {
+    options;
+
     // input: { x: number, y: number } - because y is defaulted to 2
     return input.x + input.y;
-  });
+  })
+  .callable();
 
 console.log("Test 3:", proc3({ x: 5, y: 3 }));
 
 // Test 4: Object with defaults and optionals
-const proc4 = builder()
+const proc4 = zagora()
   .input(
     z.tuple([
       z.string(),
@@ -70,11 +79,14 @@ const proc4 = builder()
       }),
     ]),
   )
-  .handler((name, config) => ({
+  .handler((options, name, config) => {
+    options;
+
     // passing!
     // config: { user: string, role: string, paid: boolean | undefined }
-    result: `${name}: role=${config.role}, paid=${config.paid ?? false}`,
-  }));
+    return `${name}: role=${config.role}, paid=${config.paid ?? false}`;
+  })
+  .callable();
 
 // SHOULD NOT REQUIRE `role` to be passed because it has a default value!
 console.log("Test 4a:", proc4("Alice", { user: "alice" }));
@@ -84,4 +96,45 @@ console.log(
   proc4("Carol", { user: "carol", role: "admin", paid: true }),
 );
 
+const ping = zagora()
+  .input(z.number())
+  .output(z.object({ pong: z.number() }))
+  .errors({
+    NOT_FOUND: z.object({ type: z.literal("NOT_FOUND"), userId: z.string() }),
+    AUTH_ERR: z.object({ type: z.literal("AUTH_ERR"), retryAfter: z.number() }),
+  })
+  .handler(({ errors }, id) => {
+    if (id === 42) {
+      throw errors.AUTH_ERR({ retryAfter: Date.now() + 1000 });
+    }
+    if (id <= 20) {
+      throw errors.NOT_FOUND({ userId: "123" });
+    }
+
+    return { pong: id + 1 };
+  })
+  .callable();
+
+// Call synchronously, no try-catch needed
+const resPing = ping(42);
+console.log("Test 5 ping-pong:", resPing);
+
+if (
+  resPing.error &&
+  resPing.isTypedError &&
+  !(resPing.error instanceof Error)
+) {
+  console.log(
+    "foo::::",
+    // Type checking now correctly infers resPing.error as PingCallableError
+    // and then further narrows it based on the 'type' property.
+    resPing.error.type === "AUTH_ERR" ? resPing.error.retryAfter : "sasa",
+    "<<<",
+  );
+} else if (resPing.error && resPing.error instanceof Error) {
+  // This block handles cases where resPing has a generic error object (e.g., an Error instance)
+  // which is not a specific typed error as defined in the .errors() method.
+  console.log("unknown err:", resPing.error);
+}
+
 console.log("\nAll tests passed!");