@corentinth/chisels - npm Package Compare versions

Comparing version 1.0.2 to 1.0.3

dist/index.d.ts

@@ -0,1 +1,11 @@
+/**
+ * Formats a number of bytes into a human-readable string.
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatBytes({ bytes: 4194304 });
+ *
+ * console.log(formatted); // 4 MiB
+ * ```
+ */
 declare function formatBytes({ bytes, decimals, base, units, }: {
@@ -8,17 +18,128 @@ bytes: number;
 
-declare function safelySync<T>(fn: () => T): [T, null] | [null, Error];
-declare function safely<T>(fn: (() => Promise<T> | T) | Promise<T>): Promise<[T, null] | [null, Error]>;
+/**
+ *  Casts an unknown value to an Error.
+ *
+ *  @example
+ *  ```typescript
+ *  try {
+ *      // ...
+ *  } catch (rawError) {
+ *    const error = castError(rawError);
+ *
+ *    // Do something with a proper Error instance
+ *  }
+ *  ```
+ */
+declare function castError(error: unknown): Error;
 
+/**
+ * Make some properties of T optional
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * };
+ *
+ * type PartialUser = PartialBy<User, 'email' | 'name'>;
+ *
+ * const user: PartialUser = { id: 1 };
+ * ```
+ */
 type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Flatten an object type for better IDE support
+ */
 type Expand<T> = T extends infer O ? {
     [K in keyof O]: O[K];
 } : never;
+/**
+ * Record<string, T> alias
+ *
+ * @example
+ * ```typescript
+ * const dictionary: Dictionary<number> = {
+ *   a: 1,
+ *   b: 2,
+ * };
+ * ```
+ */
 type Dictionary<T = unknown> = Record<string, T>;
+/**
+ * Make all properties of T optional recursively
+ */
 type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+/**
+ * Exclude properties of T that are in U
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * };
+ *
+ * type WithId = {
+ *   id: number;
+ * }
+ *
+ * type UserWithoutId = Subtract<User, WithId>;
+ * ```
+ */
 type Subtract<T, U> = Pick<T, Exclude<keyof T, keyof U>>;
 
+/**
+ *  Injects arguments into a set of functions. Useful for DI of repositories, services, etc.
+ *
+ *  @example
+ *  ```typescript
+ *  const functions = {
+ *   getUser: ({ userId, db }) => db.users.find({ id: userId }),
+ *   removeUser: ({ userId, db }) => db.users.remove({ id: userId }),
+ *  };
+ *
+ *  const { getUser, removeUser } = injectArguments(functions, { db });
+ *
+ *  getUser({ userId: 1 });
+ *  removeUser({ userId: 1 });
+ * ```
+ */
 declare function injectArguments<Functions extends Dictionary<(args: any) => any>, InjectedArgs>(functions: Functions, injectedArgs: InjectedArgs): { [K in keyof Functions]: Expand<Subtract<Parameters<Functions[K]>[0], InjectedArgs>> extends infer Args ? {} extends Args ? () => ReturnType<Functions[K]> : (args: Args) => ReturnType<Functions[K]> : never; };
 
-export { type DeepPartial, type Dictionary, type Expand, type PartialBy, type Subtract, formatBytes, injectArguments, safely, safelySync };
+/**
+ * Safely executes a function and return a tuple with the result and an error if any.
+ *
+ * @example
+ * ```typescript
+ * const [result, error] = safely(myFunction);
+ *
+ * if (error) {
+ *  console.error(error);
+ * }
+ *
+ * console.log(result);
+ * ```
+ */
+declare function safelySync<T>(fn: () => T): [T, null] | [null, Error];
+/**
+ * Safely executes an async function or promise and return a tuple with the result and an error if any.
+ *
+ * @example
+ * ```typescript
+ * const [result, error] = await safely(myFunction);
+ *
+ * if (error) {
+ *  console.error(error);
+ * }
+ *
+ * console.log(result);
+ * ```
+ */
+declare function safely<T>(fn: (() => Promise<T> | T) | Promise<T>): Promise<[T, null] | [null, Error]>;
+
+export { type DeepPartial, type Dictionary, type Expand, type PartialBy, type Subtract, castError, formatBytes, injectArguments, safely, safelySync };

package.json

 {
   "name": "@corentinth/chisels",
   "type": "module",
-  "version": "1.0.2",
-  "packageManager": "pnpm@9.2.0",
+  "version": "1.0.3",
+  "packageManager": "pnpm@9.9.0",
   "description": "Collection of utilities for JavaScript and TypeScript, lightweight and tree-shakable.",
@@ -55,3 +55,3 @@ "author": "Corentin Thomasset <[e-mail]> (https://corentin.tech)",
   "devDependencies": {
-    "@antfu/eslint-config": "^2.27.0",
+    "@antfu/eslint-config": "^3.4.1",
     "@types/lodash-es": "^4.17.12",
@@ -61,2 +61,3 @@ "@vitest/coverage-v8": "^2.0.5",
     "eslint": "^9.9.0",
+    "tsdoc-extractor": "^0.2.0",
     "tsx": "^4.19.0",
@@ -63,0 +64,0 @@ "typescript": "^5.5.4",

README.md

@@ -43,19 +43,151 @@ # Chisels - JS/TS utilities and types
 
-* Bytes
-  * [formatBytes](./src/bytes.ts)
+### `formatBytes`
 
-* Safely
-  * [safelySync](./src/safely.ts)
-  * [safely](./src/safely.ts)
+Function - [See source](./src/bytes.ts#L18)
 
-* Types
-  * [PartialBy](./src/types.ts)
-  * [Expand](./src/types.ts)
-  * [Dictionary](./src/types.ts)
-  * [DeepPartial](./src/types.ts)
-  * [Subtract](./src/types.ts)
+Formats a number of bytes into a human-readable string.
 
-* Injection
-  * [injectArguments](./src/injection.ts)
 
+```typescript
+const formatted = formatBytes({ bytes: 4194304 });
+
+console.log(formatted); // 4 MiB
+```
+
+### `castError`
+
+Function - [See source](./src/errors.ts#L19)
+
+Casts an unknown value to an Error.
+
+
+```typescript
+ try {
+     // ...
+ } catch (rawError) {
+   const error = castError(rawError);
+
+   // Do something with a proper Error instance
+ }
+ ```
+
+### `safelySync`
+
+Function - [See source](./src/safely.ts#L20)
+
+Safely executes a function and return a tuple with the result and an error if any.
+
+
+```typescript
+const [result, error] = safely(myFunction);
+
+if (error) {
+ console.error(error);
+}
+
+console.log(result);
+```
+
+### `safely`
+
+Function - [See source](./src/safely.ts#L42)
+
+Safely executes an async function or promise and return a tuple with the result and an error if any.
+
+
+```typescript
+const [result, error] = await safely(myFunction);
+
+if (error) {
+ console.error(error);
+}
+
+console.log(result);
+```
+
+### `injectArguments`
+
+Function - [See source](./src/injection.ts#L22)
+
+Injects arguments into a set of functions. Useful for DI of repositories, services, etc.
+
+
+```typescript
+ const functions = {
+  getUser: ({ userId, db }) => db.users.find({ id: userId }),
+  removeUser: ({ userId, db }) => db.users.remove({ id: userId }),
+ };
+
+ const { getUser, removeUser } = injectArguments(functions, { db });
+
+ getUser({ userId: 1 });
+ removeUser({ userId: 1 });
+```
+
+### `PartialBy`
+
+Type alias - [See source](./src/types.ts#L17)
+
+Make some properties of T optional
+
+
+```typescript
+type User = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+type PartialUser = PartialBy<User, 'email' | 'name'>;
+
+const user: PartialUser = { id: 1 };
+```
+
+### `Expand`
+
+Type alias - [See source](./src/types.ts#L22)
+
+Flatten an object type for better IDE support
+
+### `Dictionary`
+
+Type alias - [See source](./src/types.ts#L35)
+
+Record<string, T> alias
+
+
+```typescript
+const dictionary: Dictionary<number> = {
+  a: 1,
+  b: 2,
+};
+```
+
+### `DeepPartial`
+
+Type alias - [See source](./src/types.ts#L40)
+
+Make all properties of T optional recursively
+
+### `Subtract`
+
+Type alias - [See source](./src/types.ts#L64)
+
+Exclude properties of T that are in U
+
+
+```typescript
+type User = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+type WithId = {
+  id: number;
+}
+
+type UserWithoutId = Subtract<User, WithId>;
+```
+
 <!-- API-DOCS-END -->
@@ -62,0 +194,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

30842

increased by65.47%

Lines of code

237

increased by104.31%

Number of lines in readme file

201

increased by191.3%

Worsened metrics

Dev dependency count

10

increased by11.11%

No dependency changes