@forklaunch/common 0.4.5 → 0.5.0

package/lib/index.d.mts

@@ -245,6 +245,26 @@ declare function isRecord(obj: unknown): obj is Record<string, unknown>;
  */
 declare function isTrue(value: true): true;
 
+/**
+ * Computes a simple, non-cryptographic hash code for a given string.
+ *
+ * This function is synchronous and works in all JavaScript environments, including browsers and Node.js.
+ * It is suitable for basic hashing needs such as object uniqueness checks, but should NOT be used for
+ * cryptographic or security-sensitive purposes.
+ *
+ * The algorithm is based on a simple bitwise operation and may produce collisions for similar strings.
+ *
+ * @param {string} str - The input string to hash.
+ * @returns {number} The resulting hash code as a 32-bit signed integer.
+ *
+ * @example
+ * ```typescript
+ * const hash = hashStringSync("hello");
+ * console.log(hash); // e.g., 99162322
+ * ```
+ */
+declare function hashString(str: string): number;
+
 declare class InMemoryBlob extends Blob {
     content: string;
     constructor(content: string);
@@ -504,7 +524,7 @@ type MergeUnionOnCollision<T, U> = {
 };
 
 /**
- * Recursively merges an array of fetchMap objects
+ * Recursively merges an array of _fetchMap objects
  */
 type MergeArrayOfMaps<T extends readonly Record<string, unknown>[]> = T extends readonly [infer First, ...infer Rest] ? First extends Record<string, unknown> ? Rest extends readonly Record<string, unknown>[] ? Rest extends readonly [] ? First : MergeUnionOnCollision<First, MergeArrayOfMaps<Rest>> : First : Record<string, never> : Record<string, never>;
 
@@ -558,9 +578,63 @@ type StringWithoutSlash<T extends string> = T extends `${string}/${string}` ? 'c
 
 type TypeSafeFunction = (...args: never[]) => unknown;
 
+/**
+ * Utility type that converts a union type to an intersection type.
+ * Uses TypeScript's conditional type inference to transform U | V into U & V.
+ * This is a fundamental utility type used throughout the ForkLaunch framework
+ * for merging multiple types into a single intersection.
+ *
+ * @template U - The union type to convert to an intersection
+ * @param U - Any union type (e.g., A | B | C)
+ *
+ * @returns The intersection of all types in the union (e.g., A & B & C)
+ *
+ * @example
+ * ```typescript
+ * type Union = { a: string } | { b: number } | { c: boolean };
+ * type Intersection = UnionToIntersection<Union>;
+ * // Results in: { a: string } & { b: number } & { c: boolean }
+ *
+ * // Practical usage in API merging
+ * type Api1 = { users: { getUser: () => Promise<User> } };
+ * type Api2 = { posts: { getPosts: () => Promise<Post[]> } };
+ * type MergedApi = UnionToIntersection<Api1 | Api2>;
+ * // Results in: { users: { getUser: () => Promise<User> } } & { posts: { getPosts: () => Promise<Post[]> } }
+ * ```
+ */
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Applies UnionToIntersection recursively to all children of an object type.
+ * This is useful when you have an object where each property contains a union type,
+ * and you want to convert all those unions to intersections while preserving
+ * the object structure.
+ *
+ * @template U - The object type whose children should be converted
+ * @param U - An object type where each property may be a union type
+ *
+ * @returns An object type with the same keys as U, but where each value
+ *          has been processed through UnionToIntersection
+ *
+ * @example
+ * ```typescript
+ * type ApiConfig = {
+ *   users: { getUser: () => Promise<User> } | { getUser: (id: string) => Promise<User> };
+ *   posts: { getPosts: () => Promise<Post[]> } | { getPosts: (limit: number) => Promise<Post[]> };
+ * };
+ *
+ * type NormalizedApi = UnionToIntersectionChildren<ApiConfig>;
+ * // Results in:
+ * // {
+ * //   users: { getUser: () => Promise<User> } & { getUser: (id: string) => Promise<User> };
+ * //   posts: { getPosts: () => Promise<Post[]> } & { getPosts: (limit: number) => Promise<Post[]> };
+ * // }
+ *
+ * // This is particularly useful for merging multiple API configurations
+ * // where each endpoint might have multiple overloads
+ * ```
+ */
 type UnionToIntersectionChildren<U> = {
     [K in keyof U]: UnionToIntersection<U[K]>;
 };
 
-export { type CamelCaseIdentifier, type EmptyObject, type ExclusiveRecord, type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, InMemoryBlob, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type MergeArrayOfMaps, type MergeUnionOnCollision, type MimeType, type Prettify, type PrettyCamelCase, type RecordTimingDto, type RemoveDoubleLeadingSlash, type RemoveTrailingSlash, type ReturnTypeRecord, type SanitizePathSlashes, type StringWithoutSlash, type TypeSafeFunction, type UnionToIntersection, type UnionToIntersectionChildren, type ValidIdentifier, capitalize, emptyObject, extractArgumentNames, getEnvVar, getTransformationInfo, isAsyncGenerator, isNever, isNodeJsWriteableStream, isRecord, isTrue, isValidIdentifier, noop, openApiCompliantPath, readableStreamToAsyncIterable, removeDoubleLeadingSlash, removeLeadingNumbers, removeLeadingSeparators, removeNonAlphanumeric, removeTrailingSlash, safeParse, safeStringify, sanitizePathSlashes, sortObjectKeys, splitBySeparators, stripUndefinedProperties, toCamelCaseIdentifier, toPrettyCamelCase, toRecord, toValidIdentifier, uncapitalize };
+export { type CamelCaseIdentifier, type EmptyObject, type ExclusiveRecord, type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, InMemoryBlob, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type MergeArrayOfMaps, type MergeUnionOnCollision, type MimeType, type Prettify, type PrettyCamelCase, type RecordTimingDto, type RemoveDoubleLeadingSlash, type RemoveTrailingSlash, type ReturnTypeRecord, type SanitizePathSlashes, type StringWithoutSlash, type TypeSafeFunction, type UnionToIntersection, type UnionToIntersectionChildren, type ValidIdentifier, capitalize, emptyObject, extractArgumentNames, getEnvVar, getTransformationInfo, hashString, isAsyncGenerator, isNever, isNodeJsWriteableStream, isRecord, isTrue, isValidIdentifier, noop, openApiCompliantPath, readableStreamToAsyncIterable, removeDoubleLeadingSlash, removeLeadingNumbers, removeLeadingSeparators, removeNonAlphanumeric, removeTrailingSlash, safeParse, safeStringify, sanitizePathSlashes, sortObjectKeys, splitBySeparators, stripUndefinedProperties, toCamelCaseIdentifier, toPrettyCamelCase, toRecord, toValidIdentifier, uncapitalize };

package/lib/index.d.ts

@@ -245,6 +245,26 @@ declare function isRecord(obj: unknown): obj is Record<string, unknown>;
  */
 declare function isTrue(value: true): true;
 
+/**
+ * Computes a simple, non-cryptographic hash code for a given string.
+ *
+ * This function is synchronous and works in all JavaScript environments, including browsers and Node.js.
+ * It is suitable for basic hashing needs such as object uniqueness checks, but should NOT be used for
+ * cryptographic or security-sensitive purposes.
+ *
+ * The algorithm is based on a simple bitwise operation and may produce collisions for similar strings.
+ *
+ * @param {string} str - The input string to hash.
+ * @returns {number} The resulting hash code as a 32-bit signed integer.
+ *
+ * @example
+ * ```typescript
+ * const hash = hashStringSync("hello");
+ * console.log(hash); // e.g., 99162322
+ * ```
+ */
+declare function hashString(str: string): number;
+
 declare class InMemoryBlob extends Blob {
     content: string;
     constructor(content: string);
@@ -504,7 +524,7 @@ type MergeUnionOnCollision<T, U> = {
 };
 
 /**
- * Recursively merges an array of fetchMap objects
+ * Recursively merges an array of _fetchMap objects
  */
 type MergeArrayOfMaps<T extends readonly Record<string, unknown>[]> = T extends readonly [infer First, ...infer Rest] ? First extends Record<string, unknown> ? Rest extends readonly Record<string, unknown>[] ? Rest extends readonly [] ? First : MergeUnionOnCollision<First, MergeArrayOfMaps<Rest>> : First : Record<string, never> : Record<string, never>;
 
@@ -558,9 +578,63 @@ type StringWithoutSlash<T extends string> = T extends `${string}/${string}` ? 'c
 
 type TypeSafeFunction = (...args: never[]) => unknown;
 
+/**
+ * Utility type that converts a union type to an intersection type.
+ * Uses TypeScript's conditional type inference to transform U | V into U & V.
+ * This is a fundamental utility type used throughout the ForkLaunch framework
+ * for merging multiple types into a single intersection.
+ *
+ * @template U - The union type to convert to an intersection
+ * @param U - Any union type (e.g., A | B | C)
+ *
+ * @returns The intersection of all types in the union (e.g., A & B & C)
+ *
+ * @example
+ * ```typescript
+ * type Union = { a: string } | { b: number } | { c: boolean };
+ * type Intersection = UnionToIntersection<Union>;
+ * // Results in: { a: string } & { b: number } & { c: boolean }
+ *
+ * // Practical usage in API merging
+ * type Api1 = { users: { getUser: () => Promise<User> } };
+ * type Api2 = { posts: { getPosts: () => Promise<Post[]> } };
+ * type MergedApi = UnionToIntersection<Api1 | Api2>;
+ * // Results in: { users: { getUser: () => Promise<User> } } & { posts: { getPosts: () => Promise<Post[]> } }
+ * ```
+ */
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Applies UnionToIntersection recursively to all children of an object type.
+ * This is useful when you have an object where each property contains a union type,
+ * and you want to convert all those unions to intersections while preserving
+ * the object structure.
+ *
+ * @template U - The object type whose children should be converted
+ * @param U - An object type where each property may be a union type
+ *
+ * @returns An object type with the same keys as U, but where each value
+ *          has been processed through UnionToIntersection
+ *
+ * @example
+ * ```typescript
+ * type ApiConfig = {
+ *   users: { getUser: () => Promise<User> } | { getUser: (id: string) => Promise<User> };
+ *   posts: { getPosts: () => Promise<Post[]> } | { getPosts: (limit: number) => Promise<Post[]> };
+ * };
+ *
+ * type NormalizedApi = UnionToIntersectionChildren<ApiConfig>;
+ * // Results in:
+ * // {
+ * //   users: { getUser: () => Promise<User> } & { getUser: (id: string) => Promise<User> };
+ * //   posts: { getPosts: () => Promise<Post[]> } & { getPosts: (limit: number) => Promise<Post[]> };
+ * // }
+ *
+ * // This is particularly useful for merging multiple API configurations
+ * // where each endpoint might have multiple overloads
+ * ```
+ */
 type UnionToIntersectionChildren<U> = {
     [K in keyof U]: UnionToIntersection<U[K]>;
 };
 
-export { type CamelCaseIdentifier, type EmptyObject, type ExclusiveRecord, type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, InMemoryBlob, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type MergeArrayOfMaps, type MergeUnionOnCollision, type MimeType, type Prettify, type PrettyCamelCase, type RecordTimingDto, type RemoveDoubleLeadingSlash, type RemoveTrailingSlash, type ReturnTypeRecord, type SanitizePathSlashes, type StringWithoutSlash, type TypeSafeFunction, type UnionToIntersection, type UnionToIntersectionChildren, type ValidIdentifier, capitalize, emptyObject, extractArgumentNames, getEnvVar, getTransformationInfo, isAsyncGenerator, isNever, isNodeJsWriteableStream, isRecord, isTrue, isValidIdentifier, noop, openApiCompliantPath, readableStreamToAsyncIterable, removeDoubleLeadingSlash, removeLeadingNumbers, removeLeadingSeparators, removeNonAlphanumeric, removeTrailingSlash, safeParse, safeStringify, sanitizePathSlashes, sortObjectKeys, splitBySeparators, stripUndefinedProperties, toCamelCaseIdentifier, toPrettyCamelCase, toRecord, toValidIdentifier, uncapitalize };
+export { type CamelCaseIdentifier, type EmptyObject, type ExclusiveRecord, type Flatten, type FlattenKeys, type FlattenValues, type IdDto, type IdsDto, InMemoryBlob, type InstanceTypeRecord, type MakePropertyOptionalIfChildrenOptional, type MergeArrayOfMaps, type MergeUnionOnCollision, type MimeType, type Prettify, type PrettyCamelCase, type RecordTimingDto, type RemoveDoubleLeadingSlash, type RemoveTrailingSlash, type ReturnTypeRecord, type SanitizePathSlashes, type StringWithoutSlash, type TypeSafeFunction, type UnionToIntersection, type UnionToIntersectionChildren, type ValidIdentifier, capitalize, emptyObject, extractArgumentNames, getEnvVar, getTransformationInfo, hashString, isAsyncGenerator, isNever, isNodeJsWriteableStream, isRecord, isTrue, isValidIdentifier, noop, openApiCompliantPath, readableStreamToAsyncIterable, removeDoubleLeadingSlash, removeLeadingNumbers, removeLeadingSeparators, removeNonAlphanumeric, removeTrailingSlash, safeParse, safeStringify, sanitizePathSlashes, sortObjectKeys, splitBySeparators, stripUndefinedProperties, toCamelCaseIdentifier, toPrettyCamelCase, toRecord, toValidIdentifier, uncapitalize };

package/lib/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   extractArgumentNames: () => extractArgumentNames,
   getEnvVar: () => getEnvVar,
   getTransformationInfo: () => getTransformationInfo,
+  hashString: () => hashString,
   isAsyncGenerator: () => isAsyncGenerator,
   isNever: () => isNever,
   isNodeJsWriteableStream: () => isNodeJsWriteableStream,
@@ -206,6 +207,18 @@ function isTrue(value) {
   return value;
 }
 
+// src/hashString.ts
+function hashString(str) {
+  let hash = 0;
+  if (str.length === 0) return hash;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return hash;
+}
+
 // src/InMemoryBlob.ts
 var InMemoryBlob = class extends Blob {
   constructor(content) {
@@ -364,6 +377,7 @@ function toRecord(obj) {
   extractArgumentNames,
   getEnvVar,
   getTransformationInfo,
+  hashString,
   isAsyncGenerator,
   isNever,
   isNodeJsWriteableStream,

package/lib/index.mjs

@@ -150,6 +150,18 @@ function isTrue(value) {
   return value;
 }
 
+// src/hashString.ts
+function hashString(str) {
+  let hash = 0;
+  if (str.length === 0) return hash;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return hash;
+}
+
 // src/InMemoryBlob.ts
 var InMemoryBlob = class extends Blob {
   constructor(content) {
@@ -307,6 +319,7 @@ export {
   extractArgumentNames,
   getEnvVar,
   getTransformationInfo,
+  hashString,
   isAsyncGenerator,
   isNever,
   isNodeJsWriteableStream,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forklaunch/common",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Common package for base types, interfaces, implementations.",
   "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
   "bugs": {
@@ -28,16 +28,16 @@
     "lib/**"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.31.0",
-    "@types/node": "^24.0.13",
-    "@typescript/native-preview": "7.0.0-dev.20250712.1",
+    "@eslint/js": "^9.33.0",
+    "@types/node": "^24.3.0",
+    "@typescript/native-preview": "7.0.0-dev.20250820.1",
     "depcheck": "^1.4.7",
-    "eslint": "^9.31.0",
+    "eslint": "^9.33.0",
     "globals": "^16.3.0",
     "tsup": "^8.5.0",
-    "typedoc": "^0.28.7",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.36.0",
+    "typedoc": "^0.28.10",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.40.0",
     "vitest": "^3.2.4"
   },
   "scripts": {