@forklaunch/common 0.2.5 → 0.2.7

package/lib/index.d.mts

@@ -1,3 +1,23 @@
+/**
+ * Extracts the names of arguments from a function's string representation.
+ * This is useful for reflection and debugging purposes.
+ *
+ * @param {Object} func - A function or object with a toString method that returns the function definition
+ * @returns {string[]} An array of argument names
+ * @example
+ * function example(a, b, { c, d }) {}
+ * const names = extractArgumentNames(example);
+ * // Result: ['a', 'b', '{c,d}']
+ */
+declare function extractArgumentNames(func: {
+    toString(): string;
+}): string[];
+
+/**
+ * Type guard that checks if a value is of type never
+ * @param value - The value to check
+ * @returns Always returns true since this is a type guard for the never type
+ */
 declare function isNever(value: never): value is never;
 
 /**
@@ -8,21 +28,100 @@ declare function isNever(value: never): value is never;
  */
 declare function isRecord(obj: unknown): obj is Record<string, unknown>;
 
+/**
+ * Type guard that checks if a value is exactly true.
+ * This is useful for narrowing boolean types to the literal true value.
+ *
+ * @param {true} value - The value to check
+ * @returns {boolean} Always returns true since the parameter is already typed as true
+ * @example
+ * const value: boolean = true;
+ * if (isTrue(value)) {
+ *   // value is now typed as true (not just boolean)
+ * }
+ */
 declare function isTrue(value: true): true;
 
+/**
+ * A no-operation function that does nothing when called.
+ * This is commonly used as a default or placeholder function
+ * when a function parameter is optional but needs a default value.
+ *
+ * @example
+ * ```ts
+ * function withCallback(callback = noop) {
+ *   // ... do something
+ *   callback();
+ * }
+ * ```
+ */
+declare function noop(): void;
+
+/**
+ * Recursively sorts the keys of an object and its nested objects alphabetically.
+ * This is useful for consistent object serialization and comparison.
+ *
+ * @template T - The type of the object to sort
+ * @param {T} obj - The object whose keys should be sorted
+ * @returns {T} A new object with sorted keys
+ * @example
+ * const obj = { b: 2, a: 1, c: { f: 6, e: 5 } };
+ * const sorted = sortObjectKeys(obj);
+ * // Result: { a: 1, b: 2, c: { e: 5, f: 6 } }
+ */
+declare function sortObjectKeys<T extends Record<string, unknown>>(obj: T): T;
+
+/**
+ * Removes all properties with undefined values from an object. Note: this does NOT strip null values.
+ * @param obj The object to strip undefined properties from
+ * @returns A new object with all undefined properties removed
+ */
+declare function stripUndefinedProperties<T extends Record<string, unknown>>(obj: T): Partial<T>;
+
+/**
+ * Type representing a DTO (Data Transfer Object) with an id field.
+ */
 type IdDto = {
     id: string;
 };
+/**
+ * Type representing a DTO with an array of ids.
+ */
 type IdsDto = {
     ids: string[];
 };
+/**
+ * Type representing a DTO with timing information (created and updated timestamps).
+ */
 type RecordTimingDto = {
     createdAt: Date;
     updatedAt: Date;
 };
+/**
+ * Type that creates a record of return types from a record of functions.
+ *
+ * @template T - A record type where each value is a function
+ * @example
+ * type Functions = {
+ *   getName: () => string;
+ *   getAge: () => number;
+ * };
+ * type ReturnTypes = ReturnTypeRecord<Functions>; // { getName: string; getAge: number; }
+ */
 type ReturnTypeRecord<T extends Record<string, (...args: never[]) => unknown>> = {
     [K in keyof T]: ReturnType<T[K]>;
 };
+/**
+ * Type that creates a record of instance types from a record of constructors.
+ *
+ * @template T - A record type where each value is a constructor
+ * @example
+ * type Constructors = {
+ *   User: new () => User;
+ *   Post: new () => Post;
+ * };
+ * type InstanceTypes = InstanceTypeRecord<Constructors>; // { User: User; Post: Post; }
+ */
 type InstanceTypeRecord<T extends Record<string, new (...args: never[]) => unknown>> = {
     [K in keyof T]: InstanceType<T[K]>;
 };
@@ -54,7 +153,28 @@ type Flatten<T> = T extends object ? {
     [K in keyof T]: Flatten<T[K]>;
 } : T;
 
-type AllPropertiesOptional<T> = T extends Partial<T> ? Partial<T> extends T ? true : false : false;
+/**
+ * Helper type that checks if all properties of a type are optional.
+ *
+ * @template T - The type to check
+ */
+type AllPropertiesOptional<T> = T extends Partial<T> ? (Partial<T> extends T ? true : false) : false;
+/**
+ * Type that makes properties optional if all their children are optional.
+ * This is useful for creating types where properties are only optional if their nested properties are all optional.
+ *
+ * @template T - The type to transform
+ * @example
+ * type User = {
+ *   name: string;
+ *   address?: {
+ *     street?: string;
+ *     city?: string;
+ *   };
+ * };
+ * type Transformed = MakePropertyOptionalIfChildrenOptional<User>;
+ * // Result: { name: string; address?: { street?: string; city?: string; } }
+ */
 type MakePropertyOptionalIfChildrenOptional<T> = {
     [K in keyof T as AllPropertiesOptional<T[K]> extends true ? K : never]?: T[K];
 } & {
@@ -74,19 +194,14 @@ type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
 
-type RemoveTrailingSlash<T extends string> = T extends `${infer Route}/` ? Route : T;
-
-declare function extractArgumentNames(func: {
-    toString(): string;
-}): string[];
-
-declare function sortObjectKeys<T extends Record<string, unknown>>(obj: T): T;
-
 /**
- * Removes all properties with undefined values from an object. Note: this does NOT strip null values.
- * @param obj The object to strip undefined properties from
- * @returns A new object with all undefined properties removed
+ * Type that removes a trailing slash from a string type if present.
+ *
+ * @template T - The string type to process
+ * @example
+ * type Route1 = RemoveTrailingSlash<'/users/'>; // '/users'
+ * type Route2 = RemoveTrailingSlash<'/users'>;  // '/users'
  */
-declare function stripUndefinedProperties<T extends Record<string, unknown>>(obj: T): Partial<T>;
+type RemoveTrailingSlash<T extends string> = T extends `${infer Route}/` ? Route : T;
 
-export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, sortObjectKeys, stripUndefinedProperties };
+export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, noop, sortObjectKeys, stripUndefinedProperties };

package/lib/index.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Extracts the names of arguments from a function's string representation.
+ * This is useful for reflection and debugging purposes.
+ *
+ * @param {Object} func - A function or object with a toString method that returns the function definition
+ * @returns {string[]} An array of argument names
+ * @example
+ * function example(a, b, { c, d }) {}
+ * const names = extractArgumentNames(example);
+ * // Result: ['a', 'b', '{c,d}']
+ */
+declare function extractArgumentNames(func: {
+    toString(): string;
+}): string[];
+
+/**
+ * Type guard that checks if a value is of type never
+ * @param value - The value to check
+ * @returns Always returns true since this is a type guard for the never type
+ */
 declare function isNever(value: never): value is never;
 
 /**
@@ -8,21 +28,100 @@ declare function isNever(value: never): value is never;
  */
 declare function isRecord(obj: unknown): obj is Record<string, unknown>;
 
+/**
+ * Type guard that checks if a value is exactly true.
+ * This is useful for narrowing boolean types to the literal true value.
+ *
+ * @param {true} value - The value to check
+ * @returns {boolean} Always returns true since the parameter is already typed as true
+ * @example
+ * const value: boolean = true;
+ * if (isTrue(value)) {
+ *   // value is now typed as true (not just boolean)
+ * }
+ */
 declare function isTrue(value: true): true;
 
+/**
+ * A no-operation function that does nothing when called.
+ * This is commonly used as a default or placeholder function
+ * when a function parameter is optional but needs a default value.
+ *
+ * @example
+ * ```ts
+ * function withCallback(callback = noop) {
+ *   // ... do something
+ *   callback();
+ * }
+ * ```
+ */
+declare function noop(): void;
+
+/**
+ * Recursively sorts the keys of an object and its nested objects alphabetically.
+ * This is useful for consistent object serialization and comparison.
+ *
+ * @template T - The type of the object to sort
+ * @param {T} obj - The object whose keys should be sorted
+ * @returns {T} A new object with sorted keys
+ * @example
+ * const obj = { b: 2, a: 1, c: { f: 6, e: 5 } };
+ * const sorted = sortObjectKeys(obj);
+ * // Result: { a: 1, b: 2, c: { e: 5, f: 6 } }
+ */
+declare function sortObjectKeys<T extends Record<string, unknown>>(obj: T): T;
+
+/**
+ * Removes all properties with undefined values from an object. Note: this does NOT strip null values.
+ * @param obj The object to strip undefined properties from
+ * @returns A new object with all undefined properties removed
+ */
+declare function stripUndefinedProperties<T extends Record<string, unknown>>(obj: T): Partial<T>;
+
+/**
+ * Type representing a DTO (Data Transfer Object) with an id field.
+ */
 type IdDto = {
     id: string;
 };
+/**
+ * Type representing a DTO with an array of ids.
+ */
 type IdsDto = {
     ids: string[];
 };
+/**
+ * Type representing a DTO with timing information (created and updated timestamps).
+ */
 type RecordTimingDto = {
     createdAt: Date;
     updatedAt: Date;
 };
+/**
+ * Type that creates a record of return types from a record of functions.
+ *
+ * @template T - A record type where each value is a function
+ * @example
+ * type Functions = {
+ *   getName: () => string;
+ *   getAge: () => number;
+ * };
+ * type ReturnTypes = ReturnTypeRecord<Functions>; // { getName: string; getAge: number; }
+ */
 type ReturnTypeRecord<T extends Record<string, (...args: never[]) => unknown>> = {
     [K in keyof T]: ReturnType<T[K]>;
 };
+/**
+ * Type that creates a record of instance types from a record of constructors.
+ *
+ * @template T - A record type where each value is a constructor
+ * @example
+ * type Constructors = {
+ *   User: new () => User;
+ *   Post: new () => Post;
+ * };
+ * type InstanceTypes = InstanceTypeRecord<Constructors>; // { User: User; Post: Post; }
+ */
 type InstanceTypeRecord<T extends Record<string, new (...args: never[]) => unknown>> = {
     [K in keyof T]: InstanceType<T[K]>;
 };
@@ -54,7 +153,28 @@ type Flatten<T> = T extends object ? {
     [K in keyof T]: Flatten<T[K]>;
 } : T;
 
-type AllPropertiesOptional<T> = T extends Partial<T> ? Partial<T> extends T ? true : false : false;
+/**
+ * Helper type that checks if all properties of a type are optional.
+ *
+ * @template T - The type to check
+ */
+type AllPropertiesOptional<T> = T extends Partial<T> ? (Partial<T> extends T ? true : false) : false;
+/**
+ * Type that makes properties optional if all their children are optional.
+ * This is useful for creating types where properties are only optional if their nested properties are all optional.
+ *
+ * @template T - The type to transform
+ * @example
+ * type User = {
+ *   name: string;
+ *   address?: {
+ *     street?: string;
+ *     city?: string;
+ *   };
+ * };
+ * type Transformed = MakePropertyOptionalIfChildrenOptional<User>;
+ * // Result: { name: string; address?: { street?: string; city?: string; } }
+ */
 type MakePropertyOptionalIfChildrenOptional<T> = {
     [K in keyof T as AllPropertiesOptional<T[K]> extends true ? K : never]?: T[K];
 } & {
@@ -74,19 +194,14 @@ type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
 
-type RemoveTrailingSlash<T extends string> = T extends `${infer Route}/` ? Route : T;
-
-declare function extractArgumentNames(func: {
-    toString(): string;
-}): string[];
-
-declare function sortObjectKeys<T extends Record<string, unknown>>(obj: T): T;
-
 /**
- * Removes all properties with undefined values from an object. Note: this does NOT strip null values.
- * @param obj The object to strip undefined properties from
- * @returns A new object with all undefined properties removed
+ * Type that removes a trailing slash from a string type if present.
+ *
+ * @template T - The string type to process
+ * @example
+ * type Route1 = RemoveTrailingSlash<'/users/'>; // '/users'
+ * type Route2 = RemoveTrailingSlash<'/users'>;  // '/users'
  */
-declare function stripUndefinedProperties<T extends Record<string, unknown>>(obj: T): Partial<T>;
+type RemoveTrailingSlash<T extends string> = T extends `${infer Route}/` ? Route : T;
 
-export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, sortObjectKeys, stripUndefinedProperties };
+export { type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type Prettify, type RecordTimingDto, type RemoveTrailingSlash, type ReturnTypeRecord, extractArgumentNames, isNever, isRecord, isTrue, noop, sortObjectKeys, stripUndefinedProperties };

package/lib/index.js

@@ -24,27 +24,13 @@ __export(index_exports, {
   isNever: () => isNever,
   isRecord: () => isRecord,
   isTrue: () => isTrue,
+  noop: () => noop,
   sortObjectKeys: () => sortObjectKeys,
   stripUndefinedProperties: () => stripUndefinedProperties
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/guards/isNever.ts
-function isNever(value) {
-  return true;
-}
-
-// src/guards/isRecord.ts
-function isRecord(obj) {
-  return obj !== null && typeof obj === "object" && !Array.isArray(obj);
-}
-
-// src/guards/isTrue.ts
-function isTrue(value) {
-  return value;
-}
-
-// src/utils/extractArgumentNames.ts
+// src/extractArgumentNames.ts
 function extractArgumentNames(func) {
   const fnStr = func.toString();
   const args = fnStr.match(/\(([^)]*)\)/);
@@ -72,7 +58,26 @@ function extractArgumentNames(func) {
   return result;
 }
 
-// src/utils/sortObjectKeys.ts
+// src/guards/isNever.ts
+function isNever(value) {
+  return true;
+}
+
+// src/guards/isRecord.ts
+function isRecord(obj) {
+  return obj !== null && typeof obj === "object" && !Array.isArray(obj);
+}
+
+// src/guards/isTrue.ts
+function isTrue(value) {
+  return value;
+}
+
+// src/noop.ts
+function noop() {
+}
+
+// src/sortObjectKeys.ts
 function sortObjectKeys(obj) {
   if (typeof obj !== "object" || obj === null) {
     return obj;
@@ -87,7 +92,7 @@ function sortObjectKeys(obj) {
   );
 }
 
-// src/utils/stripUndefinedProperties.ts
+// src/stripUndefinedProperties.ts
 function stripUndefinedProperties(obj) {
   return Object.fromEntries(
     Object.entries(obj).filter(([, value]) => value !== void 0)
@@ -99,6 +104,7 @@ function stripUndefinedProperties(obj) {
   isNever,
   isRecord,
   isTrue,
+  noop,
   sortObjectKeys,
   stripUndefinedProperties
 });

package/lib/index.mjs

@@ -1,19 +1,4 @@
-// src/guards/isNever.ts
-function isNever(value) {
-  return true;
-}
-
-// src/guards/isRecord.ts
-function isRecord(obj) {
-  return obj !== null && typeof obj === "object" && !Array.isArray(obj);
-}
-
-// src/guards/isTrue.ts
-function isTrue(value) {
-  return value;
-}
-
-// src/utils/extractArgumentNames.ts
+// src/extractArgumentNames.ts
 function extractArgumentNames(func) {
   const fnStr = func.toString();
   const args = fnStr.match(/\(([^)]*)\)/);
@@ -41,7 +26,26 @@ function extractArgumentNames(func) {
   return result;
 }
 
-// src/utils/sortObjectKeys.ts
+// src/guards/isNever.ts
+function isNever(value) {
+  return true;
+}
+
+// src/guards/isRecord.ts
+function isRecord(obj) {
+  return obj !== null && typeof obj === "object" && !Array.isArray(obj);
+}
+
+// src/guards/isTrue.ts
+function isTrue(value) {
+  return value;
+}
+
+// src/noop.ts
+function noop() {
+}
+
+// src/sortObjectKeys.ts
 function sortObjectKeys(obj) {
   if (typeof obj !== "object" || obj === null) {
     return obj;
@@ -56,7 +60,7 @@ function sortObjectKeys(obj) {
   );
 }
 
-// src/utils/stripUndefinedProperties.ts
+// src/stripUndefinedProperties.ts
 function stripUndefinedProperties(obj) {
   return Object.fromEntries(
     Object.entries(obj).filter(([, value]) => value !== void 0)
@@ -67,6 +71,7 @@ export {
   isNever,
   isRecord,
   isTrue,
+  noop,
   sortObjectKeys,
   stripUndefinedProperties
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forklaunch/common",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Common package for base types, interfaces, implementations.",
   "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
   "bugs": {
@@ -28,14 +28,14 @@
     "lib/**"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.23.0",
+    "@eslint/js": "^9.24.0",
     "depcheck": "^1.4.7",
-    "eslint": "^9.23.0",
+    "eslint": "^9.24.0",
     "globals": "^16.0.0",
     "tsup": "^8.4.0",
-    "typedoc": "^0.28.1",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.29.0",
+    "typedoc": "^0.28.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.29.1",
     "vitest": "^3.1.1"
   },
   "scripts": {