polen 0.10.0-next.3 → 0.10.0-next.4

package/src/lib/kit-temp.ts

@@ -12,8 +12,10 @@
 //
 //
 
-import { Fs, Http, Path, Undefined } from '@wollybeard/kit'
+import { Arr, Err, Fs, Http, Path, type Ts, Undefined } from '@wollybeard/kit'
+import { never } from '@wollybeard/kit/language'
 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
@@ -60,23 +62,101 @@ export interface ImportEvent {
   context: ResolveHookContext
 }
 
-export const ObjPick = <T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K> => {
-  return keys.reduce((acc, key) => {
-    if (key in obj) {
-      acc[key] = obj[key]
+// dprint-ignore
+export type ObjPolicyFilter<
+  $Object extends object,
+  $Key extends Keyof<$Object>,
+  Mode extends 'allow' | 'deny',
+> = Mode extends 'allow'
+      ? Pick<$Object, Extract<$Key, keyof $Object>>
+      : Omit<$Object, Extract<$Key, keyof $Object>>
+
+/**
+ * Like keyof but returns PropertyKey for object
+ */
+type Keyof<$Object extends object> = object extends $Object ? PropertyKey : (keyof $Object)
+
+/**
+ * Filter object properties based on a policy mode and set of keys
+ *
+ * @param mode - 'allow' to keep only specified keys, 'deny' to remove specified keys
+ * @param obj - The object to filter
+ * @param keys - The keys to process
+ * @returns A filtered object with proper type inference
+ *
+ * @example
+ * ```ts
+ * const obj = { a: 1, b: 2, c: 3 }
+ *
+ * // Allow mode: keep only 'a' and 'c'
+ * objPolicyFilter('allow', obj, ['a', 'c']) // { a: 1, c: 3 }
+ *
+ * // Deny mode: remove 'a' and 'c'
+ * objPolicyFilter('deny', obj, ['a', 'c']) // { b: 2 }
+ * ```
+ */
+export const objPolicyFilter = <
+  obj extends object,
+  keyUnion extends Keyof<obj>,
+  mode extends 'allow' | 'deny',
+>(
+  mode: mode,
+  obj: obj,
+  keys: readonly keyUnion[],
+): ObjPolicyFilter<obj, keyUnion, mode> => {
+  const result: any = mode === 'deny' ? { ...obj } : {}
+
+  if (mode === 'allow') {
+    // For allow mode, only add specified keys
+    for (const key of keys) {
+      if (key in obj) {
+        // @ts-expect-error
+        result[key] = obj[key]
+      }
     }
-    return acc
-  }, {} as Pick<T, K>)
+  } else {
+    // For deny mode, remove specified keys
+    for (const key of keys) {
+      delete result[key]
+    }
+  }
+
+  return result
 }
 
-export const ObjOmit = <T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K> => {
-  return keys.reduce((acc, key) => {
-    if (key in acc) {
-      // @ts-expect-error omitted already at type level
-      delete acc[key]
+/**
+ * Filter an object using a predicate function
+ *
+ * @param obj - The object to filter
+ * @param predicate - Function that returns true to keep a key/value pair
+ * @returns A new object with only the key/value pairs where predicate returned true
+ *
+ * @example
+ * ```ts
+ * const obj = { a: 1, b: 2, c: 3 }
+ * objFilter(obj, (k, v) => v > 1) // { b: 2, c: 3 }
+ * objFilter(obj, k => k !== 'b') // { a: 1, c: 3 }
+ * ```
+ */
+export const objFilter = <T extends object>(
+  obj: T,
+  predicate: (key: keyof T, value: T[keyof T], obj: T) => boolean,
+): Partial<T> => {
+  const result = {} as Partial<T>
+  for (const key in obj) {
+    if (predicate(key, obj[key], obj)) {
+      result[key] = obj[key]
     }
-    return acc
-  }, { ...obj } as Omit<T, K>)
+  }
+  return result
+}
+
+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
+}
+
+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
 }
 
 export const ObjPartition = <T extends object, K extends keyof T>(
@@ -106,3 +186,35 @@ export const ResponseInternalServerError = () =>
     status: Http.Status.InternalServerError.code,
     statusText: Http.Status.InternalServerError.description,
   })
+
+/**
+ * Execute an operation on multiple items, continuing even if some fail
+ */
+export async function tryCatchMany<item, result>(
+  items: item[],
+  operation: (item: item) => Promise<result>,
+): Promise<[result[], (Error & { context: { item: item } })[]]> {
+  const partitionedResults = await Promise.all(items.map(async (item) => {
+    const result = await Err.tryCatch(() => operation(item))
+    if (Err.is(result)) {
+      const error = result as Error & { context: { item: item } }
+      error.context = { item }
+      return error
+    }
+    return result
+  })).then(Arr.partitionErrors)
+  return partitionedResults as any
+}
+
+/**
+ * Type-level helper to check if two types are exactly the same (invariant).
+ */
+export type IsExact<T, U> = T extends U ? U extends T ? true : false : false
+
+// dprint-ignore
+export type ExtendsExact<$Input, $Constraint> =
+  $Input extends $Constraint
+    ? $Constraint extends $Input
+      ? $Input
+      : never
+  : never

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

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

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

@@ -0,0 +1,248 @@
+import * as fc from 'fast-check'
+import { describe, expect, test } from 'vitest'
+import { Mask } from './$.ts'
+
+describe('Mask.create', () => {
+  test('boolean options create binary masks', () => {
+    const showMask = Mask.create(true)
+    const hideMask = Mask.create(false)
+
+    expect(showMask.type).toBe('binary')
+    expect(hideMask.type).toBe('binary')
+
+    if (showMask.type === 'binary' && hideMask.type === 'binary') {
+      expect(showMask.show).toBe(true)
+      expect(hideMask.show).toBe(false)
+    }
+  })
+
+  test('array options create allow mode properties mask', () => {
+    const mask = Mask.create(['name', 'age'])
+
+    expect(mask.type).toBe('properties')
+    if (mask.type === 'properties') {
+      expect(mask.mode).toBe('allow')
+      expect(mask.properties).toEqual(['name', 'age'])
+    }
+  })
+
+  test('object options create mode based on values', () => {
+    const allowMask = Mask.create({ name: true, age: true, password: false })
+    const denyMask = Mask.create({ password: false, secret: false })
+
+    expect(allowMask.type).toBe('properties')
+    expect(denyMask.type).toBe('properties')
+
+    if (allowMask.type === 'properties' && denyMask.type === 'properties') {
+      expect(allowMask.mode).toBe('allow')
+      expect(allowMask.properties).toEqual(['name', 'age'])
+
+      expect(denyMask.mode).toBe('deny')
+      expect(denyMask.properties).toEqual(['password', 'secret'])
+    }
+  })
+})
+
+describe('Mask.apply', () => {
+  test('binary masks show/hide data', () => {
+    const data = { a: 1 }
+
+    expect(Mask.apply(data, Mask.create(true))).toBe(data)
+    expect(Mask.apply(data, Mask.create(false))).toBe(undefined)
+  })
+
+  test('properties masks filter objects', () => {
+    const data = { name: 'John', age: 30, password: 'secret' }
+
+    // Allow mode
+    const allowMask = Mask.create(['name', 'age'])
+    expect(Mask.apply(data, allowMask)).toEqual({ name: 'John', age: 30 })
+
+    // Deny mode
+    const denyMask = Mask.create({ password: false })
+    expect(Mask.apply(data, denyMask)).toEqual({ name: 'John', age: 30 })
+  })
+
+  test('properties masks throw for non-objects', () => {
+    const mask = Mask.create(['name'])
+
+    expect(() => Mask.apply('string' as any, mask)).toThrow()
+    expect(() => Mask.apply(123 as any, mask)).toThrow()
+    expect(() => Mask.apply(null as any, mask)).toThrow()
+  })
+})
+
+describe('apply variants', () => {
+  test('applyPartial allows missing properties', () => {
+    const mask = Mask.create<{ name: string; age: number }>(['name', 'age'])
+    const partial = { name: 'John' }
+
+    expect(Mask.applyPartial(partial, mask)).toEqual({ name: 'John' })
+    expect(Mask.applyPartial({}, mask)).toEqual({})
+  })
+
+  test('applyExact works with any data for binary masks', () => {
+    const showMask = Mask.create(true)
+    const hideMask = Mask.create(false)
+
+    expect(Mask.applyExact('hello' as any, showMask)).toBe('hello')
+    expect(Mask.applyExact('hello' as any, hideMask)).toBe(undefined)
+  })
+})
+
+describe('property-based tests', () => {
+  test('binary masks - invariants', () => {
+    fc.assert(
+      fc.property(fc.anything(), (data) => {
+        expect(Mask.apply(data, Mask.create(true))).toBe(data)
+        expect(Mask.apply(data, Mask.create(false))).toBe(undefined)
+      }),
+    )
+  })
+
+  test('properties mask - allow mode filters correctly', () => {
+    fc.assert(
+      fc.property(
+        fc.dictionary(fc.string(), fc.anything()),
+        fc.array(fc.string(), { minLength: 1 }),
+        (obj, keys) => {
+          const mask = Mask.create(keys)
+          const result = Mask.apply(obj as any, mask)
+          const resultKeys = Object.keys(result as any)
+
+          // Result contains only keys that were in both mask and object
+          expect(resultKeys.every(key => keys.includes(key))).toBe(true)
+
+          // All requested keys that exist in obj are in result
+          keys.forEach(key => {
+            if (key in obj) {
+              expect(result).toHaveProperty(key, (obj as any)[key])
+            }
+          })
+        },
+      ),
+    )
+  })
+
+  test('properties mask - deny mode filters correctly', () => {
+    fc.assert(
+      fc.property(
+        fc.dictionary(fc.string(), fc.anything()),
+        fc.uniqueArray(fc.string(), { minLength: 1 }),
+        (data, keysToRemove) => {
+          const maskSpec = Object.fromEntries(keysToRemove.map(k => [k, false]))
+          const mask = Mask.create(maskSpec)
+
+          expect(mask.type).toBe('properties')
+          if (mask.type !== 'properties') return
+          expect(mask.mode).toBe('deny')
+
+          const result = Mask.apply(data as any, mask)
+
+          // Result should not have any of the denied keys
+          keysToRemove.forEach(key => {
+            expect(Object.prototype.hasOwnProperty.call(result, key)).toBe(false)
+          })
+
+          // Result should have all other keys from data
+          Object.keys(data).forEach(key => {
+            if (!keysToRemove.includes(key)) {
+              expect(Object.prototype.hasOwnProperty.call(result, key)).toBe(true)
+              expect((result as any)[key]).toBe((data as any)[key])
+            }
+          })
+        },
+      ),
+    )
+  })
+
+  test('undefined values are preserved', () => {
+    fc.assert(
+      fc.property(
+        fc.record({
+          a: fc.oneof(fc.anything(), fc.constant(undefined)),
+          b: fc.oneof(fc.anything(), fc.constant(undefined)),
+          c: fc.oneof(fc.anything(), fc.constant(undefined)),
+        }),
+        fc.shuffledSubarray(['a', 'b', 'c'], { minLength: 1 }),
+        (obj, keys) => {
+          const result = Mask.apply(obj as any, Mask.create(keys))
+
+          keys.forEach(key => {
+            if (key in obj) {
+              expect(result).toHaveProperty(key)
+              expect((result as any)[key]).toBe((obj as any)[key])
+            }
+          })
+        },
+      ),
+    )
+  })
+
+  test('apply and applyPartial are consistent for complete data', () => {
+    fc.assert(
+      fc.property(
+        fc.dictionary(fc.string(), fc.anything()),
+        fc.array(fc.string(), { minLength: 1 }),
+        (data, keys) => {
+          const mask = Mask.create(keys)
+          expect(Mask.apply(data as any, mask)).toEqual(Mask.applyPartial(data as any, mask))
+        },
+      ),
+    )
+  })
+
+  test('non-objects throw with properties masks', () => {
+    fc.assert(
+      fc.property(
+        fc.oneof(
+          fc.string(),
+          fc.integer(),
+          fc.boolean(),
+          fc.constant(null),
+          fc.constant(undefined),
+        ),
+        fc.array(fc.string(), { minLength: 1 }),
+        (nonObject, keys) => {
+          const mask = Mask.create(keys)
+          expect(() => Mask.apply(nonObject as any, mask)).toThrow('Cannot apply properties mask to non-object data')
+        },
+      ),
+    )
+  })
+
+  test('immutability invariants', () => {
+    fc.assert(
+      fc.property(
+        fc.dictionary(
+          fc.string(),
+          fc.oneof(
+            fc.string(),
+            fc.integer(),
+            fc.boolean(),
+            fc.constant(null),
+          ),
+        ),
+        fc.oneof(
+          fc.boolean(),
+          fc.array(fc.string()),
+          fc.dictionary(fc.string(), fc.boolean()),
+        ),
+        (data, maskOptions) => {
+          const mask = Mask.create(maskOptions as any)
+          const originalData = { ...data }
+          const originalMask = JSON.parse(JSON.stringify(mask))
+
+          try {
+            Mask.apply(data as any, mask)
+          } catch {
+            // Ignore errors for invalid combinations
+          }
+
+          expect(data).toEqual(originalData)
+          expect(mask).toEqual(originalMask)
+        },
+      ),
+    )
+  })
+})

package/src/lib/mask/$.ts

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

package/src/lib/mask/apply.ts

@@ -0,0 +1,134 @@
+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'
+
+/**
+ * Type-level function that applies a mask to data.
+ *
+ * @template Data - The data type
+ * @template M - The mask type
+ *
+ * Binary masks:
+ * - show=true returns the data unchanged
+ * - show=false returns undefined
+ *
+ * Properties masks:
+ * - 'allow' mode returns Pick<Data, keys>
+ * - 'deny' mode returns Omit<Data, keys>
+ * - 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
+        ? Data
+        : undefined
+      : 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>>
+          : never  // Non-objects not allowed with property masks
+        : never
+
+/**
+ * Apply mask to data with standard covariance.
+ *
+ * Data must be assignable to the mask's expected type (may have excess properties).
+ *
+ * @param data - The data to mask
+ * @param mask - The mask to apply
+ * @returns The masked data
+ *
+ * @example
+ * ```ts
+ * const user = { name: 'John', email: 'john@example.com', password: 'secret' }
+ * const mask = Mask.pick<User>(['name', 'email'])
+ * const safeUser = apply(user, mask) // { name: 'John', email: 'john@example.com' }
+ * ```
+ */
+export const apply = <
+  data extends GetDataType<mask>,
+  mask extends Mask<any>,
+>(data: data, mask: mask): Apply<data, mask> => {
+  return applyInternal(data, mask) as Apply<data, mask>
+}
+
+/**
+ * Apply mask to partial data.
+ *
+ * Data may have only a subset of the mask's expected properties.
+ * Useful when working with incomplete data or optional fields.
+ *
+ * @param data - The partial data to mask
+ * @param mask - The mask to apply
+ * @returns The masked data
+ *
+ * @example
+ * ```ts
+ * const partialUser = { name: 'John' } // missing email
+ * const mask = Mask.pick<User>(['name', 'email'])
+ * const result = applyPartial(partialUser, mask) // { name: 'John' }
+ * ```
+ */
+export const applyPartial = <
+  data extends Partial<GetDataType<mask>>,
+  mask extends Mask<any>,
+>(data: data, mask: mask): Apply<data, mask> => {
+  return applyInternal(data, mask) as Apply<data, mask>
+}
+
+/**
+ * Apply mask to data with exact type matching.
+ *
+ * Data must exactly match the mask's expected type - no missing or excess properties.
+ * Provides the strictest type checking.
+ *
+ * @param data - The data to mask (must exactly match expected type)
+ * @param mask - The mask to apply
+ * @returns The masked data
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; email: string }
+ * const mask = Mask.pick<User>(['name'])
+ *
+ * // This works - exact match
+ * const user: User = { name: 'John', email: 'john@example.com' }
+ * const result = applyExact(user, mask)
+ *
+ * // This fails - has extra property
+ * const userWithExtra = { name: 'John', email: 'john@example.com', age: 30 }
+ * const result2 = applyExact(userWithExtra, mask) // Type error!
+ * ```
+ */
+export const applyExact = <
+  data,
+  mask extends Mask<any>,
+>(
+  data: ExtendsExact<data, GetDataType<mask>>,
+  mask: mask,
+): Apply<data, mask> => {
+  return applyInternal(data, mask) as Apply<data, mask>
+}
+
+// Internal implementation
+const applyInternal = (data: any, mask: Mask<any>): any => {
+  // ━ Handle binary mask
+  if (mask.type === 'binary') {
+    return mask.show ? data : undefined
+  }
+
+  // ━ Handle properties mask
+  if (mask.type === 'properties') {
+    // Properties mask requires object data
+    if (!Obj.is(data)) {
+      throw new Error('Cannot apply properties mask to non-object data')
+    }
+
+    return objPolicyFilter(mask.mode, data, mask.properties)
+  }
+
+  never()
+}

package/src/lib/mask/mask.test-d.ts

@@ -0,0 +1,144 @@
+import { Ts } from '@wollybeard/kit'
+import { Mask } from './$.ts'
+import type { InferOptions, Mask as MaskType, PropertiesMask } from './mask.ts'
+
+// Test 1: InferOptions with unknown should accept all option types
+{
+  type Options = InferOptions<unknown>
+
+  // This is a type-level assertion - we need to use a different pattern
+  type _Test = Ts.AssertEqual<Options, boolean | string[] | Record<string, boolean>>
+
+  // All of these should be valid options
+  const option1: Options = true
+  const option2: Options = false
+  const option3: Options = ['name', 'age']
+  const option4: Options = []
+  const option5: Options = { name: true, age: false }
+  const option6: Options = {}
+}
+
+// Test 2: Mask.create with unknown data type should accept all option types
+{
+  // Boolean options
+  const mask1 = Mask.create(true)
+  const mask2 = Mask.create(false)
+  // Without explicit type parameter, returns union type
+  Ts.assertEqual<MaskType<unknown>>()(mask1)
+  Ts.assertEqual<MaskType<unknown>>()(mask2)
+
+  // Array options (no type parameter needed)
+  const mask3 = Mask.create(['name', 'age'])
+  const mask4 = Mask.create([])
+  const mask5 = Mask.create(['a', 'b', 'c'])
+  // Returns union type with inferred properties
+  Ts.assertEqual<MaskType<{ name: any; age: any }>>()(mask3)
+  Ts.assertEqual<MaskType<unknown>>()(mask4)
+  Ts.assertEqual<MaskType<{ a: any; b: any; c: any }>>()(mask5)
+
+  // Object options
+  const mask6 = Mask.create({ name: true, age: false })
+  const mask7 = Mask.create({})
+  const mask8 = Mask.create({ foo: true, bar: true, baz: false })
+  // Returns union type with inferred properties
+  Ts.assertEqual<MaskType<unknown>>()(mask6)
+  Ts.assertEqual<MaskType<unknown>>()(mask7)
+  Ts.assertEqual<MaskType<unknown>>()(mask8)
+}
+
+// Test 3: With specific data type, options are constrained
+{
+  type User = { name: string; age: number; email: string }
+
+  // Valid options
+  const mask1 = Mask.create<User>(true)
+  const mask2 = Mask.create<User>(['name', 'age'])
+  const mask3 = Mask.create<User>({ name: true, age: false, email: true })
+
+  // With explicit type parameter, still returns union type
+  Ts.assertEqual<MaskType<User>>()(mask1)
+  Ts.assertEqual<MaskType<User>>()(mask2)
+  Ts.assertEqual<MaskType<User>>()(mask3)
+
+  // Invalid cases would be compile errors
+  // const mask4 = Mask.create<User>(['invalid']) // Error: 'invalid' is not a key of User
+  // const mask5 = Mask.create<User>({ invalid: true }) // Error: 'invalid' is not a property of User
+}
+
+// Test 4: Non-object types only accept boolean
+{
+  const mask1 = Mask.create<string>(true)
+  const mask2 = Mask.create<string>(false)
+
+  Ts.assertEqual<MaskType<string>>()(mask1)
+  Ts.assertEqual<MaskType<string>>()(mask2)
+
+  // Invalid cases would be compile errors
+  // const mask3 = Mask.create<string>(['prop']) // Error: string is not an object
+  // const mask4 = Mask.create<string>({ prop: true }) // Error: string is not an object
+}
+
+// Test 5: Test inference in practical scenarios
+{
+  // Should infer PropertiesMask with object data type
+  const userMask = Mask.create(['name', 'email', 'password'])
+  Ts.assertEqual<MaskType<{ name: any; email: any; password: any }>>()(userMask)
+
+  // When mask is a union type, apply returns a union of possible results
+  const user1 = { name: 'John', email: 'john@example.com', password: 'secret', extra: 'data' }
+  const maskedUser1 = Mask.apply(user1, userMask)
+  // Result is a union type that includes the properties mask result
+  type MaskedUser1 = typeof maskedUser1
+  // Can't use assertSub with union types
+
+  // For partial data, use applyPartial
+  const user2 = { name: 'Jane', email: 'jane@example.com' }
+  const maskedUser2 = Mask.applyPartial(user2, userMask)
+  // Result is a union type
+  type MaskedUser2 = typeof maskedUser2
+}
+
+// Test 6: Pick and omit helpers
+{
+  const pick1 = Mask.pick(['name', 'email'])
+  const omit1 = Mask.omit(['password', 'secret'])
+
+  // Infers specific property types
+  Ts.assertEqual<PropertiesMask<{ name: any; email: any }>>()(pick1)
+  Ts.assertEqual<PropertiesMask<{ password: any; secret: any }>>()(omit1)
+
+  type User = { name: string; email: string; password: string }
+  const pick2 = Mask.pick<User>(['name', 'email'])
+  const omit2 = Mask.omit<User>(['password'])
+
+  Ts.assertEqual<PropertiesMask<User>>()(pick2)
+  Ts.assertEqual<PropertiesMask<User>>()(omit2)
+}
+
+// Test 7: Apply type transformations
+{
+  type User = { name: string; email: string; password: string }
+  const user: User = { name: 'John', email: 'john@example.com', password: 'secret' }
+
+  // Binary mask
+  const showMask = Mask.create<User>(true)
+  const hideMask = Mask.create<User>(false)
+  const shown = Mask.apply(user, showMask)
+  const hidden = Mask.apply(user, hideMask)
+
+  // showMask and hideMask are MaskType<User> (union types), so results are unions
+  type ShownType = typeof shown // Omit<User, keyof User> | undefined
+  type HiddenType = typeof hidden // Omit<User, keyof User> | undefined
+
+  // Properties mask - allow mode
+  const allowMask = Mask.create<User>(['name', 'email'])
+  const allowed = Mask.apply(user, allowMask)
+  // Result is a union due to mask being a union type
+  type AllowedType = typeof allowed
+
+  // Properties mask - deny mode
+  const denyMask = Mask.create<User>({ password: false })
+  const denied = Mask.apply(user, denyMask)
+  // Result is a union due to mask being a union type
+  type DeniedType = typeof denied
+}