Support async rules in eager enforce(value) chains with awaitable chains and type updates

packages/n4s/src/__tests__/asyncEnforce.types.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { enforce } from '../n4s';
+
+declare global {
+  namespace n4s {
+    interface EnforceMatchers {
+      isAsyncPass: (value: string) => Promise<{ pass: boolean }>;
+    }
+  }
+}
+
+function syncTypeChecks() {
+  enforce('sync')
+    .isString()
+    // @ts-expect-error - sync-only chains should not expose promise methods at type level
+    .then(() => undefined);
+}
+
+describe('Async Enforce Types', () => {
+  void syncTypeChecks;
+
+  it('should allow awaiting the enforce chain after async rule is invoked', async () => {
+    enforce.extend({
+      isAsyncPass: async (value: string) => ({ pass: value.length > 0 }),
+    });
+
+    const result: void = await enforce('test').isString().isAsyncPass();
+    expect(result).toBeUndefined();
+  });
+});

packages/n4s/src/__tests__/extend.test.ts

@@ -629,14 +629,12 @@ describe('enforce.extend', () => {
   });
 
   describe('Async behavior considerations', () => {
-    it('Should handle custom rules that might be used async (returning promises should fail sync)', () => {
+    it('Should handle custom rules that return promises', async () => {
       enforce.extend({
-        // This simulates someone accidentally returning a promise
         asyncRule: () => Promise.resolve(true),
       });
 
-      // In n4spath, invalid return values should throw
-      expect(() => enforce('test').asyncRule()).toThrow();
+      await expect(enforce('test').asyncRule()).resolves.toBeUndefined();
     });
   });