polen 0.10.0-next.8 → 0.10.0

package/src/lib/kit-temp.ts

@@ -12,10 +12,8 @@
 //
 //
 
-import { Arr, Err, Fs, Http, Path, type Ts, Undefined } from '@wollybeard/kit'
-import { never } from '@wollybeard/kit/language'
+import { Arr, Err, Fs, Http, Path, Undefined } from '@wollybeard/kit'
 import type { ResolveHookContext } from 'node:module'
-import type { IsNever } from 'type-fest'
 
 export const arrayEquals = (a: any[], b: any[]) => {
   if (a.length !== b.length) return false
@@ -66,8 +64,8 @@ export interface ImportEvent {
 export type ObjPolicyFilter<
   $Object extends object,
   $Key extends Keyof<$Object>,
-  Mode extends 'allow' | 'deny',
-> = Mode extends 'allow'
+  Mode extends `allow` | `deny`,
+> = Mode extends `allow`
       ? Pick<$Object, Extract<$Key, keyof $Object>>
       : Omit<$Object, Extract<$Key, keyof $Object>>
 
@@ -98,15 +96,15 @@ type Keyof<$Object extends object> = object extends $Object ? PropertyKey : (key
 export const objPolicyFilter = <
   obj extends object,
   keyUnion extends Keyof<obj>,
-  mode extends 'allow' | 'deny',
+  mode extends `allow` | `deny`,
 >(
   mode: mode,
   obj: obj,
   keys: readonly keyUnion[],
 ): ObjPolicyFilter<obj, keyUnion, mode> => {
-  const result: any = mode === 'deny' ? { ...obj } : {}
+  const result: any = mode === `deny` ? { ...obj } : {}
 
-  if (mode === 'allow') {
+  if (mode === `allow`) {
     // For allow mode, only add specified keys
     for (const key of keys) {
       if (key in obj) {
@@ -143,7 +141,9 @@ export const objFilter = <T extends object>(
   predicate: (key: keyof T, value: T[keyof T], obj: T) => boolean,
 ): Partial<T> => {
   const result = {} as Partial<T>
-  for (const key in obj) {
+  // Use Object.keys to get all enumerable own properties
+  // This matches the behavior of for...in but only for own properties
+  for (const key of Object.keys(obj) as (keyof T)[]) {
     if (predicate(key, obj[key], obj)) {
       result[key] = obj[key]
     }
@@ -152,11 +152,11 @@ export const objFilter = <T extends object>(
 }
 
 export const ObjPick = <T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K> => {
-  return objPolicyFilter('allow', obj, keys) as any
+  return objPolicyFilter(`allow`, obj, keys) as any
 }
 
 export const ObjOmit = <T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K> => {
-  return objPolicyFilter('deny', obj, keys) as any
+  return objPolicyFilter(`deny`, obj, keys) as any
 }
 
 export const ObjPartition = <T extends object, K extends keyof T>(
@@ -218,3 +218,428 @@ export type ExtendsExact<$Input, $Constraint> =
       ? $Input
       : never
   : never
+
+/**
+ * Split an array into chunks of specified size
+ *
+ * @param array - The array to chunk
+ * @param size - The size of each chunk
+ * @returns Array of chunks
+ *
+ * @example
+ * ```ts
+ * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+ * chunk(['a', 'b', 'c'], 3) // [['a', 'b', 'c']]
+ * ```
+ */
+export const chunk = <T>(array: readonly T[], size: number): T[][] => {
+  if (size <= 0) throw new Error(`Chunk size must be greater than 0`)
+  if (array.length === 0) return []
+
+  const chunks: T[][] = []
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size))
+  }
+  return chunks
+}
+
+export interface AsyncParallelOptions {
+  /**
+   * Maximum number of items to process concurrently
+   * @default 10
+   */
+  concurrency?: number
+
+  /**
+   * If true, stops processing on first error
+   * If false, continues processing all items even if some fail
+   * @default false
+   */
+  failFast?: boolean
+
+  /**
+   * Size of batches to process items in
+   * If not specified, all items are processed with the specified concurrency
+   */
+  batchSize?: number
+}
+
+export interface AsyncParallelResult<T, R> {
+  /** Successfully processed results */
+  results: R[]
+  /** Errors that occurred during processing */
+  errors: (Error & { item: T })[]
+  /** Whether all items were processed successfully */
+  success: boolean
+}
+
+/**
+ * Process items in parallel with configurable options
+ *
+ * @param items - Items to process
+ * @param operation - Async function to apply to each item (with optional index)
+ * @param options - Configuration options
+ * @returns Results and errors from processing
+ *
+ * @example
+ * ```ts
+ * const items = [1, 2, 3, 4, 5]
+ * const result = await asyncParallel(items, async (n, index) => n * 2, {
+ *   concurrency: 2,
+ *   batchSize: 3,
+ *   failFast: false
+ * })
+ * // result.results: [2, 4, 6, 8, 10]
+ * // result.errors: []
+ * // result.success: true
+ * ```
+ */
+export const asyncParallel = async <T, R>(
+  items: readonly T[],
+  operation: (item: T, index: number) => Promise<R>,
+  options: AsyncParallelOptions = {},
+): Promise<AsyncParallelResult<T, R>> => {
+  const { concurrency = 10, failFast = false, batchSize } = options
+
+  if (items.length === 0) {
+    return { results: [], errors: [], success: true }
+  }
+
+  const allResults: R[] = []
+  const allErrors: (Error & { item: T })[] = []
+
+  // If batchSize is specified, process in batches
+  if (batchSize !== undefined) {
+    const batches = chunk(items, batchSize)
+    let globalIndex = 0
+
+    for (const batch of batches) {
+      const batchResult = await processBatch(batch, operation, concurrency, failFast, globalIndex)
+      allResults.push(...batchResult.results)
+      allErrors.push(...batchResult.errors)
+      globalIndex += batch.length
+
+      if (failFast && batchResult.errors.length > 0) {
+        break
+      }
+    }
+  } else {
+    // Process all items with specified concurrency
+    const result = await processBatch(items, operation, concurrency, failFast, 0)
+    allResults.push(...result.results)
+    allErrors.push(...result.errors)
+  }
+
+  return {
+    results: allResults,
+    errors: allErrors,
+    success: allErrors.length === 0,
+  }
+}
+
+/**
+ * Process a batch of items with limited concurrency
+ */
+const processBatch = async <T, R>(
+  items: readonly T[],
+  operation: (item: T, index: number) => Promise<R>,
+  concurrency: number,
+  failFast: boolean,
+  startIndex = 0,
+): Promise<AsyncParallelResult<T, R>> => {
+  const results: R[] = []
+  const errors: (Error & { item: T })[] = []
+
+  // Process items in chunks based on concurrency limit
+  const chunks = chunk(items, concurrency)
+  let currentIndex = startIndex
+
+  for (const chunkItems of chunks) {
+    const promises = chunkItems.map(async (item, chunkIndex) => {
+      const globalIndex = currentIndex + chunkIndex
+      try {
+        const result = await operation(item, globalIndex)
+        return { success: true, result, item }
+      } catch (error) {
+        const enhancedError = error instanceof Error ? error : new Error(String(error))
+        Object.assign(enhancedError, { item })
+        return { success: false, error: enhancedError as Error & { item: T }, item }
+      }
+    })
+
+    currentIndex += chunkItems.length
+
+    const chunkResults = await Promise.allSettled(promises)
+
+    for (const promiseResult of chunkResults) {
+      if (promiseResult.status === `fulfilled`) {
+        const { success, result, error, item } = promiseResult.value
+        if (success) {
+          results.push(result!)
+        } else {
+          errors.push(error!)
+          if (failFast) {
+            return { results, errors, success: false }
+          }
+        }
+      } else {
+        // This shouldn't happen since we're catching errors above
+        // But handle it just in case
+        const error = new Error(`Unexpected promise rejection`) as Error & { item: any }
+        errors.push(error)
+        if (failFast) {
+          return { results, errors, success: false }
+        }
+      }
+    }
+  }
+
+  return { results, errors, success: errors.length === 0 }
+}
+
+// /**
+//  * Reduce an array asynchronously, processing each item in sequence
+//  *
+//  * @param items - Array of items to process
+//  * @param reducer - Async function that takes accumulator and current item
+//  * @param initial - Initial value for the accumulator
+//  * @returns Final accumulated value
+//  *
+//  * @example
+//  * ```ts
+//  * const numbers = [1, 2, 3, 4]
+//  * const sum = await asyncReduce(numbers, async (acc, n) => acc + n, 0)
+//  * // sum: 10
+//  *
+//  * const transforms = [addHeader, addFooter, minify]
+//  * const html = await asyncReduce(transforms, async (html, transform) => transform(html), initialHtml)
+//  * ```
+//  */
+// export const asyncReduce = async <T, R>(
+//   items: readonly T[],
+//   reducer: (accumulator: R, current: T, index: number) => Promise<R> | R,
+//   initial: R,
+// ): Promise<R> => {
+//   let result = initial
+//   for (let i = 0; i < items.length; i++) {
+//     const item = items[i]!
+//     result = await reducer(result, item, i)
+//   }
+//   return result
+// }
+
+// /**
+//  * Curried version of asyncReduce for functions that transform a value
+//  *
+//  * @param transformers - Array of transformer functions
+//  * @returns A function that takes an initial value and applies all transformers
+//  *
+//  * @example
+//  * ```ts
+//  * const transformers = [addHeader, addFooter, minify]
+//  * const applyTransforms = asyncReduceWith(transformers)
+//  * const finalHtml = await applyTransforms(initialHtml)
+//  *
+//  * // For simple pipelines where each function transforms the same type
+//  * const htmlPipeline = asyncReduceWith([
+//  *   (html) => html.replace('foo', 'bar'),
+//  *   async (html) => await prettify(html),
+//  *   (html) => html.trim()
+//  * ])
+//  * ```
+//  */
+// export const asyncReduceWith = <T>(
+//   transformers: readonly ((value: T) => Promise<T> | T)[],
+// ) => {
+//   return async (initial: T): Promise<T> => {
+//     return asyncReduce(transformers, (value, transform) => transform(value), initial)
+//   }
+// }
+
+/**
+ * Reduce an array asynchronously with context, processing each item in sequence
+ *
+ * @param items - Array of items to process
+ * @param reducer - Async function that takes accumulator, current item, and context
+ * @param initial - Initial value for the accumulator
+ * @param context - Context object passed to each reducer call
+ * @returns Final accumulated value
+ *
+ * @example
+ * ```ts
+ * const transformers = [transformer1, transformer2]
+ * const ctx = { request: req, response: res }
+ * const result = await asyncReduceWithContext(
+ *   transformers,
+ *   async (html, transformer) => transformer(html, ctx),
+ *   initialHtml,
+ *   ctx
+ * )
+ * ```
+ */
+export const asyncReduce = async <T, R, C>(
+  items: readonly T[],
+  reducer: (accumulator: R, current: T, context: C, index: number) => Promise<R> | R,
+  initial: R,
+  context: C,
+): Promise<R> => {
+  let result = initial
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]!
+    result = await reducer(result, item, context, i)
+  }
+  return result
+}
+
+/**
+ * Curried version of asyncReduceWithContext for functions that transform a value with context
+ *
+ * @param transformers - Array of transformer functions that take value and context
+ * @returns A function that takes an initial value and context, and applies all transformers
+ *
+ * @example
+ * ```ts
+ * const transformers = [
+ *   (html, ctx) => html.replace('{{url}}', ctx.req.url),
+ *   async (html, ctx) => await ctx.minify(html),
+ * ]
+ * const applyTransforms = asyncReduceWithContextWith(transformers)
+ * const finalHtml = await applyTransforms(initialHtml, ctx)
+ * ```
+ */
+export const asyncReduceWith = <T, C>(
+  transformers: readonly ((value: T, context: C) => Promise<T> | T)[],
+  context: C,
+) => {
+  return async (initial: T): Promise<T> => {
+    return asyncReduce(
+      transformers,
+      (value, transform, ctx) => transform(value, ctx),
+      initial,
+      context,
+    )
+  }
+}
+
+/**
+ * Create a branded type that provides nominal typing in TypeScript.
+ *
+ * Branded types allow you to create distinct types from primitives or other types,
+ * preventing accidental mixing of values that are structurally identical but
+ * semantically different.
+ *
+ * @template $BaseType - The underlying type to brand (e.g., string, number)
+ * @template $BrandName - A unique string literal to distinguish this brand
+ *
+ * @example
+ * ```ts
+ * // Create distinct ID types that can't be mixed
+ * type UserId = Brand<string, 'UserId'>
+ * type PostId = Brand<string, 'PostId'>
+ *
+ * function getUser(id: UserId) { ... }
+ *
+ * const userId = 'u123' as UserId
+ * const postId = 'p456' as PostId
+ *
+ * getUser(userId)  // ✓ OK
+ * getUser(postId)  // ✗ Type error - can't use PostId where UserId expected
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Brand primitive types for domain modeling
+ * type Email = Brand<string, 'Email'>
+ * type Url = Brand<string, 'Url'>
+ * type PositiveNumber = Brand<number, 'PositiveNumber'>
+ * ```
+ */
+export type Brand<$BaseType, $BrandName extends string> =
+  & $BaseType
+  & {
+    readonly __brand: $BrandName
+  }
+
+/**
+ * Helper function to create a branded value.
+ *
+ * This is a simple type assertion helper. For runtime validation,
+ * combine with validation functions or schemas.
+ *
+ * @template $BaseType - The underlying type to brand
+ * @template $BrandName - The brand name to apply
+ * @param value - The value to brand
+ * @returns The value with the brand type applied
+ *
+ * @example
+ * ```ts
+ * type UserId = Brand<string, 'UserId'>
+ *
+ * // Simple branding (no runtime validation)
+ * const id = brand<string, 'UserId'>('u123')
+ *
+ * // With validation (recommended)
+ * function createUserId(value: string): UserId {
+ *   if (!value.startsWith('u')) {
+ *     throw new Error('User IDs must start with "u"')
+ *   }
+ *   return brand<string, 'UserId'>(value)
+ * }
+ * ```
+ */
+export const brand = <$BaseType, $BrandName extends string>(
+  value: $BaseType,
+): Brand<$BaseType, $BrandName> => {
+  return value as Brand<$BaseType, $BrandName>
+}
+
+/**
+ * Shallow merge objects while omitting undefined values.
+ *
+ * This utility simplifies the common pattern of conditionally spreading objects
+ * to avoid including undefined values that would override existing values.
+ *
+ * @param objects - Objects to merge (later objects override earlier ones). Undefined objects are ignored.
+ * @returns Merged object with undefined values omitted
+ *
+ * @example
+ * ```ts
+ * // Instead of:
+ * const overrides = {
+ *   ...(value1 ? { key1: value1 } : {}),
+ *   ...(value2 ? { key2: value2 } : {}),
+ * }
+ *
+ * // Use:
+ * const overrides = mergeShallow({
+ *   key1: value1,
+ *   key2: value2,
+ * })
+ *
+ * // Example with config merging:
+ * const config = mergeShallow(
+ *   defaultConfig,
+ *   userConfig,
+ *   { debug: args.debug, base: args.base }
+ * )
+ * // undefined values in the last object won't override earlier values
+ * ```
+ */
+export const spreadShallow = <T extends object>(...objects: (T | undefined)[]): T => {
+  const result = {} as T
+
+  for (const obj of objects) {
+    if (obj === undefined) continue
+
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        const value = obj[key]
+        if (value !== undefined) {
+          result[key] = value
+        }
+      }
+    }
+  }
+
+  return result
+}

package/src/lib/mask/$$.ts

@@ -1,2 +1,2 @@
-export * from './apply.ts'
-export * from './mask.ts'
+export * from './apply.js'
+export * from './mask.js'

package/src/lib/mask/$.test.ts

@@ -1,6 +1,6 @@
 import * as fc from 'fast-check'
 import { describe, expect, test } from 'vitest'
-import { Mask } from './$.ts'
+import { Mask } from './$.js'
 
 describe('Mask.create', () => {
   test('boolean options create binary masks', () => {

package/src/lib/mask/$.ts

@@ -1 +1 @@
-export * as Mask from './$$.ts'
+export * as Mask from './$$.js'

package/src/lib/mask/apply.ts

@@ -1,7 +1,7 @@
 import { type ExtendsExact, objPolicyFilter } from '#lib/kit-temp'
 import { Obj } from '@wollybeard/kit'
 import { never } from '@wollybeard/kit/language'
-import type { GetDataType, Mask } from './mask.ts'
+import type { GetDataType, Mask } from './mask.js'
 
 /**
  * Type-level function that applies a mask to data.
@@ -19,16 +19,16 @@ import type { GetDataType, Mask } from './mask.ts'
  * - Non-objects throw an error at runtime
  */
 // dprint-ignore
-export type Apply<Data, M extends Mask<any>> =
-    M extends { type: 'binary', show: boolean }
-      ? M['show'] extends true
+export type Apply<Data, M extends Mask> =
+    M extends { type: `binary`, show: boolean }
+      ? M[`show`] extends true
         ? Data
         : undefined
-      : M extends { type: 'properties', mode: string, properties: any[] }
+      : M extends { type: `properties`, mode: string, properties: any[] }
         ? Data extends object
-          ? M['mode'] extends 'allow'
-            ? Pick<Data, Extract<M['properties'][number], keyof Data>>
-            : Omit<Data, Extract<M['properties'][number], keyof Data>>
+          ? M[`mode`] extends `allow`
+            ? Pick<Data, Extract<M[`properties`][number], keyof Data>>
+            : Omit<Data, Extract<M[`properties`][number], keyof Data>>
           : never  // Non-objects not allowed with property masks
         : never
 
@@ -50,7 +50,7 @@ export type Apply<Data, M extends Mask<any>> =
  */
 export const apply = <
   data extends GetDataType<mask>,
-  mask extends Mask<any>,
+  mask extends Mask,
 >(data: data, mask: mask): Apply<data, mask> => {
   return applyInternal(data, mask) as Apply<data, mask>
 }
@@ -74,7 +74,7 @@ export const apply = <
  */
 export const applyPartial = <
   data extends Partial<GetDataType<mask>>,
-  mask extends Mask<any>,
+  mask extends Mask,
 >(data: data, mask: mask): Apply<data, mask> => {
   return applyInternal(data, mask) as Apply<data, mask>
 }
@@ -105,7 +105,7 @@ export const applyPartial = <
  */
 export const applyExact = <
   data,
-  mask extends Mask<any>,
+  mask extends Mask,
 >(
   data: ExtendsExact<data, GetDataType<mask>>,
   mask: mask,
@@ -114,17 +114,17 @@ export const applyExact = <
 }
 
 // Internal implementation
-const applyInternal = (data: any, mask: Mask<any>): any => {
+const applyInternal = (data: any, mask: Mask): any => {
   // ━ Handle binary mask
-  if (mask.type === 'binary') {
+  if (mask.type === `binary`) {
     return mask.show ? data : undefined
   }
 
   // ━ Handle properties mask
-  if (mask.type === 'properties') {
+  if (mask.type === `properties`) {
     // Properties mask requires object data
     if (!Obj.is(data)) {
-      throw new Error('Cannot apply properties mask to non-object data')
+      throw new Error(`Cannot apply properties mask to non-object data`)
     }
 
     return objPolicyFilter(mask.mode, data, mask.properties)