@ntangled/kit 0.0.0-alpha.0 → 0.0.0-alpha.1

package/README.md

@@ -1,3 +1,59 @@
 # @ntangled/kit
 
 A TypeScript utililty package.
+
+## Safe
+
+The `safe.ts` module provides utility functions for safely executing synchronous and asynchronous code, ensuring that errors are handled gracefully and never thrown. Instead, each function returns a tuple of `[error, result]`, making error handling explicit and consistent.
+
+> [!IMPORTANT]  
+> Throwing `null` will result in a NullError in the error entry. Use `instance of NullError` if you expect `null` to be thrown.
+
+### Utilities
+
+- **NullError**: Custom error thrown when a `null` value is encountered where not expected.
+- **px**: Safely executes an async callback, returns `[error, result]`.
+- **rx**: Safely executes a sync callback, returns `[error, result]`.
+- **pw**: Wraps an async function, returns a new function that always returns `[error, result]`.
+- **rw**: Wraps a sync function, returns a new function that always returns `[error, result]`.
+
+### Usage
+
+#### px (Promise Executor)
+
+```ts
+const [err, data] = await px(async () => await fetchData());
+if (err) {
+	// handle error
+}
+```
+
+#### rx (Result Executor)
+
+```ts
+const [err, value] = rx(() => computeValue());
+if (err) {
+	// handle error
+}
+```
+
+#### pw (Promise Wrapper)
+
+```ts
+const safeFetch = pw(fetchData);
+const [err, data] = await safeFetch(arg1, arg2);
+```
+
+#### rw (Result Wrapper)
+
+```ts
+const safeCompute = rw(computeValue);
+const [err, value] = safeCompute(arg1, arg2);
+```
+
+### Why use Safe utilities?
+
+- Avoids try/catch boilerplate.
+- Makes error handling explicit and consistent.
+- Works for both sync and async functions.
+- Prevents uncaught exceptions and null errors.

package/dist/safe.d.ts

@@ -1,26 +1,57 @@
-export type NonNull = NonNullable<unknown>;
 /**
- * @name px
- * @alias safe promise executor
- * @param callback
+ * Error thrown when a null value is encountered where not expected.
+ * @class NullError
+ * @extends Error
+ */
+export declare class NullError extends Error {
+    constructor();
+}
+/**
+ * Safely executes an async callback, returning a tuple of [error, result].
+ * Never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - An async function to execute.
+ * @returns {Promise<[NonNull|null, Awaited<ReturnType<Callback>>|null]>} Tuple: [error, result].
+ * @example
+ *   const [err, data] = await px(async () => await fetchData());
  */
 export declare const px: <Callback extends () => unknown>(callback: Callback) => Promise<[null, Awaited<ReturnType<Callback>>] | readonly [{}, null]>;
 /**
- * @name rx
- * @alias safe result executor
- * @param callback
+ * Safely executes a synchronous callback, returning a tuple of [error, result].
+ * Never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - A synchronous function to execute.
+ * @returns {[NonNull|null, ReturnType<Callback>|null]} Tuple: [error, result].
+ * @example
+ *   const [err, value] = rx(() => computeValue());
  */
 export declare const rx: <Callback extends () => unknown>(callback: Callback) => readonly [{}, null] | [null, ReturnType<Callback>];
 /**
- * @name pw
- * @alias safe promise wrapper
- * @param callback
+ * Wraps an async function to always return a tuple of [error, result].
+ * Returned function never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - An async function to wrap.
+ * @returns {(...params: Parameters<Callback>) => Promise<[NonNull|null, Awaited<ReturnType<Callback>>|null]>}
+ *   Wrapped function returning [error, result].
+ * @example
+ *   const safeFetch = pw(fetchData);
+ *   const [err, data] = await safeFetch(arg1, arg2);
  */
 export declare const pw: <Callback extends (...params: any[]) => unknown>(callback: Callback) => (...params: Parameters<Callback>) => Promise<readonly [{}, null] | [null, Awaited<ReturnType<Callback>>]>;
 /**
- * @name rw
- * @alias safe result wrapper
- * @param callback
+ * Wraps a synchronous function to always return a tuple of [error, result].
+ * Returned function never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - A synchronous function to wrap.
+ * @returns {(...params: Parameters<Callback>) => [NonNull|null, ReturnType<Callback>|null]}
+ *   Wrapped function returning [error, result].
+ * @example
+ *   const safeCompute = rw(computeValue);
+ *   const [err, value] = safeCompute(arg1, arg2);
  */
 export declare const rw: <Callback extends (...params: any[]) => unknown>(callback: Callback) => (...params: Parameters<Callback>) => readonly [{}, null] | [null, ReturnType<Callback>];
 //# sourceMappingURL=safe.d.ts.map

package/dist/safe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe.d.ts","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,EAAE,GAAU,QAAQ,SAAS,MAAM,OAAO,EAAE,UAAU,QAAQ,yEAQ1E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,EAAE,GAAI,QAAQ,SAAS,MAAM,OAAO,EAAE,UAAU,QAAQ,uDAQpE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,EAAE,GAAI,QAAQ,SAAS,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,UAAU,QAAQ,MACtE,GAAG,QAAQ,UAAU,CAAC,QAAQ,CAAC,yEAS7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,EAAE,GAAI,QAAQ,SAAS,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,UAAU,QAAQ,MAC5E,GAAG,QAAQ,UAAU,CAAC,QAAQ,CAAC,uDASvC,CAAC"}
+{"version":3,"file":"safe.d.ts","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;;CAMnC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,EAAE,GAAU,QAAQ,SAAS,MAAM,OAAO,EAAE,UAAU,QAAQ,yEAQ1E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,EAAE,GAAI,QAAQ,SAAS,MAAM,OAAO,EAAE,UAAU,QAAQ,uDAQpE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,EAAE,GAAI,QAAQ,SAAS,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,UAAU,QAAQ,MACtE,GAAG,QAAQ,UAAU,CAAC,QAAQ,CAAC,yEAS7C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,EAAE,GAAI,QAAQ,SAAS,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,UAAU,QAAQ,MAC5E,GAAG,QAAQ,UAAU,CAAC,QAAQ,CAAC,uDASvC,CAAC"}

package/dist/safe.js

@@ -1,7 +1,24 @@
 /**
- * @name px
- * @alias safe promise executor
- * @param callback
+ * Error thrown when a null value is encountered where not expected.
+ * @class NullError
+ * @extends Error
+ */
+export class NullError extends Error {
+    constructor() {
+        super('null');
+        this.name = 'NullError';
+        Object.setPrototypeOf(this, NullError.prototype);
+    }
+}
+/**
+ * Safely executes an async callback, returning a tuple of [error, result].
+ * Never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - An async function to execute.
+ * @returns {Promise<[NonNull|null, Awaited<ReturnType<Callback>>|null]>} Tuple: [error, result].
+ * @example
+ *   const [err, data] = await px(async () => await fetchData());
  */
 export const px = async (callback) => {
     try {
@@ -10,14 +27,19 @@ export const px = async (callback) => {
     }
     catch (error) {
         if (error === null)
-            return [new Error('null'), null];
+            return [new NullError(), null];
         return [error, null];
     }
 };
 /**
- * @name rx
- * @alias safe result executor
- * @param callback
+ * Safely executes a synchronous callback, returning a tuple of [error, result].
+ * Never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - A synchronous function to execute.
+ * @returns {[NonNull|null, ReturnType<Callback>|null]} Tuple: [error, result].
+ * @example
+ *   const [err, value] = rx(() => computeValue());
  */
 export const rx = (callback) => {
     try {
@@ -26,14 +48,21 @@ export const rx = (callback) => {
     }
     catch (error) {
         if (error === null)
-            return [new Error('null'), null];
+            return [new NullError(), null];
         return [error, null];
     }
 };
 /**
- * @name pw
- * @alias safe promise wrapper
- * @param callback
+ * Wraps an async function to always return a tuple of [error, result].
+ * Returned function never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - An async function to wrap.
+ * @returns {(...params: Parameters<Callback>) => Promise<[NonNull|null, Awaited<ReturnType<Callback>>|null]>}
+ *   Wrapped function returning [error, result].
+ * @example
+ *   const safeFetch = pw(fetchData);
+ *   const [err, data] = await safeFetch(arg1, arg2);
  */
 export const pw = (callback) => {
     return async (...params) => {
@@ -43,15 +72,22 @@ export const pw = (callback) => {
         }
         catch (error) {
             if (error === null)
-                return [new Error('null'), null];
+                return [new NullError(), null];
             return [error, null];
         }
     };
 };
 /**
- * @name rw
- * @alias safe result wrapper
- * @param callback
+ * Wraps a synchronous function to always return a tuple of [error, result].
+ * Returned function never throws; errors are returned as the first tuple element.
+ *
+ * @template Callback
+ * @param {Callback} callback - A synchronous function to wrap.
+ * @returns {(...params: Parameters<Callback>) => [NonNull|null, ReturnType<Callback>|null]}
+ *   Wrapped function returning [error, result].
+ * @example
+ *   const safeCompute = rw(computeValue);
+ *   const [err, value] = safeCompute(arg1, arg2);
  */
 export const rw = (callback) => {
     return (...params) => {
@@ -61,7 +97,7 @@ export const rw = (callback) => {
         }
         catch (error) {
             if (error === null)
-                return [new Error('null'), null];
+                return [new NullError(), null];
             return [error, null];
         }
     };

package/dist/safe.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe.js","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,KAAK,EAAkC,QAAkB,EAAE,EAAE;IAC9E,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,EAAE,MAAM,CAA0C,CAAC;IAChE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,KAAK,CAAC,MAAM,CAAY,EAAE,IAAI,CAAU,CAAC;QACzE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;IAC1C,CAAC;AACF,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAiC,QAAkB,EAAE,EAAE;IACxE,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,CAAiC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,KAAK,CAAC,MAAM,CAAY,EAAE,IAAI,CAAU,CAAC;QACzE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;IAC1C,CAAC;AACF,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAiD,QAAkB,EAAE,EAAE;IACxF,OAAO,KAAK,EAAE,GAAG,MAA4B,EAAE,EAAE;QAChD,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,EAAE,MAAM,CAA0C,CAAC;QAChE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,CAAC,IAAI,KAAK,CAAC,MAAM,CAAY,EAAE,IAAI,CAAU,CAAC;YACzE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;QAC1C,CAAC;IACF,CAAC,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAiD,QAAkB,EAAE,EAAE;IACxF,OAAO,CAAC,GAAG,MAA4B,EAAE,EAAE;QAC1C,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC;YACnC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAiC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,CAAC,IAAI,KAAK,CAAC,MAAM,CAAY,EAAE,IAAI,CAAU,CAAC;YACzE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;QAC1C,CAAC;IACF,CAAC,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"file":"safe.js","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACnC;QACC,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;CACD;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,KAAK,EAAkC,QAAkB,EAAE,EAAE;IAC9E,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,EAAE,MAAM,CAA0C,CAAC;IAChE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,SAAS,EAAa,EAAE,IAAI,CAAU,CAAC;QACvE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;IAC1C,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAiC,QAAkB,EAAE,EAAE;IACxE,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,CAAiC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,SAAS,EAAa,EAAE,IAAI,CAAU,CAAC;QACvE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;IAC1C,CAAC;AACF,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAiD,QAAkB,EAAE,EAAE;IACxF,OAAO,KAAK,EAAE,GAAG,MAA4B,EAAE,EAAE;QAChD,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,EAAE,MAAM,CAA0C,CAAC;QAChE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,CAAC,IAAI,SAAS,EAAa,EAAE,IAAI,CAAU,CAAC;YACvE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;QAC1C,CAAC;IACF,CAAC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAiD,QAAkB,EAAE,EAAE;IACxF,OAAO,CAAC,GAAG,MAA4B,EAAE,EAAE;QAC1C,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC;YACnC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAiC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,CAAC,IAAI,SAAS,EAAa,EAAE,IAAI,CAAU,CAAC;YACvE,OAAO,CAAC,KAAgB,EAAE,IAAI,CAAU,CAAC;QAC1C,CAAC;IACF,CAAC,CAAC;AACH,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type NonNull = NonNullable<unknown>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ntangled/kit",
-	"version": "0.0.0-alpha.0",
+	"version": "0.0.0-alpha.1",
 	"main": "dist/main.js",
 	"types": "dist/main.d.ts",
 	"files": [