@ntangled/kit 0.0.0-alpha.6 → 0.0.1

package/README.md

@@ -1,59 +1,209 @@
 # @ntangled/kit
 
-A TypeScript utililty package.
+A lightweight, zero-dependency utility for TypeScript. Works seamlessly in **Node.js**, **Bun** and the **Browser**.
 
-## Safe
+> Disclaimer: This is my first "serious" npm lib. There will be typos, bad formulated paragraphs and more - and you are more than welcome to notify me.
 
-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.
+## Features
 
-> [!IMPORTANT]  
-> Throwing `null` will result in a NullError in the error entry. Use `instance of NullError` if you expect `null` to be thrown.
+- **Universal**: Works in any environment (Node, Bun, Deno, Browsers).
 
-### Utilities
+- **Dual-Build**: Ships with ESM and CommonJS support.
 
-- **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]`.
+- **Type-Safe**: Full TypeScript support with inference for both sync and async functions.
 
-### Usage
+- **Tiny**: Zero dependencies and minimal footprint.
 
-#### px (Promise Executor)
+## Installation
+
+```bash
+npm install @ntangled/kit
+```
+
+```bash
+yarn add @ntangled/kit
+```
+
+```bash
+bun add @ntangled/kit
+```
+
+```bash
+pnpm install @ntangled/kit
+```
+
+## Documentation
+
+### `s` (Safe)
+
+A lightweight utility for **Go-style error handling** in TypeScript.
+
+Stop nesting your code in `try/catch` blocks. Use `w` (wrap) and `x` (execute) to handle errors as values.
+
+#### Usage
+
+You can import the core utilities from the main entry point or directly from the `safe` subpath. Combine this with `Guard clauses` (_fast exist_) and your error handling becomes much easier.
+
+> Guard clauses are awesome and makes the code more readable and easier to extend. It is not a library but a design pattern you can learn in less than a minute.
 
 ```ts
-const [err, data] = await px(async () => await fetchData());
-if (err) {
-	// handle error
+import { x, w } from '@ntangled/kit/safe';
+// or
+import { s } from '@ntangled/kit';
+```
+
+#### Simple Example
+
+```ts
+import { x } from '@ntangled/kit/safe';
+
+const foo = () => {
+	const [error, value] = x(() => 'Hello safe' as const);
+
+	/*
+		type error is : {} | null
+		{} meaning everything sinde an error can be every thing
+
+		type value is : null | 'Hello safe'
+	*/
+
+	if (error !== null) return console.error(error);
+
+	/*
+		type error is : null
+		type value is : 'Hello safe'
+	*/
+
+	console.log(result.foo); // 'bar'
+};
+
+foo();
+```
+
+> Note on conditions: The `error` must explicitly be match to not `null` because of the type system.
+
+> Note on return: The early return `Guard clause` is what make the type system work.
+
+If the function you call doesn't return anything you can simply just omit the second entry (`value`). The error will still be return so you can handle it.
+
+#### `x` (Execute)
+
+Executes a function immediately and returns a `[error, result]` tuple.
+
+**Synchronous**
+
+```ts
+const [error, result] = x(() => JSON.parse('{"foo": "bar"}'));
+
+if (error !== null) return console.error(error);
+console.log(result.foo); // 'bar'
+```
+
+**Asynchronous**
+
+```ts
+const [fetchErr, response] = await x(() => fetch('https://api.example.com'));
+if (fetchErr) {
+	// Handle network error
 }
 ```
 
-#### rx (Result Executor)
+#### `w` (Wrap)
+
+Wraps a function and returns a new version of that function that always returns a `[error, result]` tuple. This is perfect for defining "safe" versions of existing functions.
+
+Wrapping is useful for functions that already are defined like core JavaScript functions like `JSON.parse`, third-party libraries or your own functions if they already are used and rewriting them is hard do to the other implementations.
 
 ```ts
-const [err, value] = rx(() => computeValue());
-if (err) {
-	// handle error
+const safeJsonParse = w(JSON.parse);
+
+const [err, data] = safeJsonParse('invalid json');
+// err is now a SyntaxError instead of throwing
+```
+
+#### Handling Errors
+
+If you have a function that can trow multiple different errors and you want to handle them accordingly you can use the `instanceof` operator. By using this operator TypeScript knows the type within the scope so you can work with its properties.
+
+```ts
+import { x, NullError } from '@ntangled/kit/safe';
+
+const foo () => {
+	const [error] = x(bar); // bar is just a random function name
+
+	if (error !== null) {
+		// in this scope we know error exits
+
+		if (error instanceof NullError) return console.error('A null was thrown');
+		if (error instanceof TypeError) return console.error('A TypeError was thrown');
+		// ...
+
+		return console.error('A unknown error was thrown');
+	}
+
+	// if there is no error you can safely continue your code here...
+}
+```
+
+**Making a custom error**
+
+Making custom errors can be useful. With this you can add properties to the error and then access them after using the `instanceof` operator.
+
+```ts
+export class ValueError extends Error {
+	constructor(message: string, value: string) {
+		super(message);
+		this.name = 'ValueError';
+
+		//  this is a custom value added when the error is thrown
+		this.value = value;
+
+		// this makes the instanceof work
+		Object.setPrototypeOf(this, ValueError.prototype);
+	}
 }
+
+// usage
+throw new ValueError('message arg', 'value arg');
 ```
 
-#### pw (Promise Wrapper)
+#### Handling `null` Errors
+
+If your code throws `null` (which is technically possible in JS), this library catches it and returns a specific `NullError` class to ensure your error variable is always an actual object.
 
 ```ts
-const safeFetch = pw(fetchData);
-const [err, data] = await safeFetch(arg1, arg2);
+import { NullError } from '@ntangled/kit/safe';
+
+const [error] = x(() => {
+	throw null;
+});
+
+console.log(error instanceof NullError); // true
 ```
 
-#### rw (Result Wrapper)
+#### Why use this?
+
+Standard `try/catch` blocks create extra indentation and scope-lock your variables:
+
+**The old way:**
 
 ```ts
-const safeCompute = rw(computeValue);
-const [err, value] = safeCompute(arg1, arg2);
+let data;
+
+try {
+	data = JSON.parse(str);
+} catch (error) {
+	// handle error
+}
+
+console.log(data); // data is available here, but the code is messy
 ```
 
-### Why use Safe utilities?
+**The `safe` way:**
+
+```ts
+const [error, data] = x(() => JSON.parse(str));
+if (error) return handle(error);
 
-- Avoids try/catch boilerplate.
-- Makes error handling explicit and consistent.
-- Works for both sync and async functions.
-- Prevents uncaught exceptions and null errors.
+console.log(data); // Clean, flat, and type-safe
+```

package/dist/safe.d.mts

@@ -8,8 +8,54 @@ import { NonNull } from './types.mjs';
 declare class NullError extends Error {
     constructor();
 }
+/**
+ * Wraps a callback function (sync or async) and returns a function that executes the callback,
+ * capturing errors and returning them in a tuple. For async callbacks, errors are caught and returned
+ * as the first element of the tuple, and the resolved value as the second. For sync callbacks, errors
+ * are caught and returned similarly.
+ *
+ * @template Callback - The type of the callback function.
+ * @param callback - The callback function to wrap.
+ * @returns A function that, when called, returns a tuple: [error, result]. If no error occurs, error is null.
+ *          For async callbacks, returns a Promise resolving to the tuple.
+ *
+ * @example
+ * // Synchronous usage
+ * const safeAdd = w((a: number, b: number) => a + b);
+ * const [err, sum] = safeAdd(1, 2);
+ *
+ * // Asynchronous usage
+ * const safeFetch = w(async (url: string) => fetch(url));
+ * const [err, response] = await safeFetch('https://example.com');
+ */
 declare function w<Callback extends (...params: any[]) => Promise<any>>(callback: Callback): (...params: Parameters<Callback>) => Promise<[NonNull, null] | [null, Awaited<ReturnType<Callback>>]>;
 declare function w<Callback extends (...params: any[]) => any>(callback: Callback): (...params: Parameters<Callback>) => [NonNull, null] | [null, ReturnType<Callback>];
+/**
+ * Executes a callback function (sync or async) immediately, capturing errors and returning them in a tuple.
+ * You can pass an already defined function (e.g. x(foo())) or an anonymous function (e.g. x(() => 'hello world')).
+ * Both can be async.
+ *
+ * @template Callback - The type of the callback function.
+ * @param callback - The callback function to execute.
+ * @param params - Parameters to pass to the callback function.
+ * @returns A tuple: [error, result]. If no error occurs, error is null.
+ *          For async callbacks, returns a Promise resolving to the tuple.
+ *
+ * @example
+ * // Synchronous usage with anonymous function
+ * const [err, result] = x(() => 'hello world');
+ *
+ * // Synchronous usage with defined function
+ * function foo() { return 42; }
+ * const [err, result] = x(foo);
+ *
+ * // Asynchronous usage with anonymous function
+ * const [err, result] = await x(async () => await fetch('https://example.com'));
+ *
+ * // Asynchronous usage with defined function
+ * async function fetchData() { return await fetch('https://example.com'); }
+ * const [err, result] = await x(fetchData);
+ */
 declare function x<Callback extends (...params: any[]) => Promise<any>>(callback: Callback, ...params: Parameters<Callback>): Promise<[NonNull, null] | [null, Awaited<ReturnType<Callback>>]>;
 declare function x<Callback extends (...params: any[]) => any>(callback: Callback, ...params: Parameters<Callback>): [NonNull, null] | [null, ReturnType<Callback>];
 

package/dist/safe.d.ts

@@ -8,8 +8,54 @@ import { NonNull } from './types.js';
 declare class NullError extends Error {
     constructor();
 }
+/**
+ * Wraps a callback function (sync or async) and returns a function that executes the callback,
+ * capturing errors and returning them in a tuple. For async callbacks, errors are caught and returned
+ * as the first element of the tuple, and the resolved value as the second. For sync callbacks, errors
+ * are caught and returned similarly.
+ *
+ * @template Callback - The type of the callback function.
+ * @param callback - The callback function to wrap.
+ * @returns A function that, when called, returns a tuple: [error, result]. If no error occurs, error is null.
+ *          For async callbacks, returns a Promise resolving to the tuple.
+ *
+ * @example
+ * // Synchronous usage
+ * const safeAdd = w((a: number, b: number) => a + b);
+ * const [err, sum] = safeAdd(1, 2);
+ *
+ * // Asynchronous usage
+ * const safeFetch = w(async (url: string) => fetch(url));
+ * const [err, response] = await safeFetch('https://example.com');
+ */
 declare function w<Callback extends (...params: any[]) => Promise<any>>(callback: Callback): (...params: Parameters<Callback>) => Promise<[NonNull, null] | [null, Awaited<ReturnType<Callback>>]>;
 declare function w<Callback extends (...params: any[]) => any>(callback: Callback): (...params: Parameters<Callback>) => [NonNull, null] | [null, ReturnType<Callback>];
+/**
+ * Executes a callback function (sync or async) immediately, capturing errors and returning them in a tuple.
+ * You can pass an already defined function (e.g. x(foo())) or an anonymous function (e.g. x(() => 'hello world')).
+ * Both can be async.
+ *
+ * @template Callback - The type of the callback function.
+ * @param callback - The callback function to execute.
+ * @param params - Parameters to pass to the callback function.
+ * @returns A tuple: [error, result]. If no error occurs, error is null.
+ *          For async callbacks, returns a Promise resolving to the tuple.
+ *
+ * @example
+ * // Synchronous usage with anonymous function
+ * const [err, result] = x(() => 'hello world');
+ *
+ * // Synchronous usage with defined function
+ * function foo() { return 42; }
+ * const [err, result] = x(foo);
+ *
+ * // Asynchronous usage with anonymous function
+ * const [err, result] = await x(async () => await fetch('https://example.com'));
+ *
+ * // Asynchronous usage with defined function
+ * async function fetchData() { return await fetch('https://example.com'); }
+ * const [err, result] = await x(fetchData);
+ */
 declare function x<Callback extends (...params: any[]) => Promise<any>>(callback: Callback, ...params: Parameters<Callback>): Promise<[NonNull, null] | [null, Awaited<ReturnType<Callback>>]>;
 declare function x<Callback extends (...params: any[]) => any>(callback: Callback, ...params: Parameters<Callback>): [NonNull, null] | [null, ReturnType<Callback>];
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ntangled/kit",
-	"version": "0.0.0-alpha.6",
+	"version": "0.0.1",
 	"description": "A TypeScript utility package for safe function execution and other helpers.",
 	"author": "Stephan D. <stephan.mdd@gmail.com>",
 	"homepage": "https://github.com/ntangled/kit#readme",