polen 0.10.0-next.14 → 0.10.0-next.3

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

@@ -1,144 +0,0 @@
-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
-}

package/src/lib/mask/mask.ts

@@ -1,244 +0,0 @@
-//
-//
-//
-//
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Mask
-//
-//
-
-/**
- * A mask that can either hide/show data entirely (BinaryMask) or
- * selectively hide/show object properties (PropertiesMask).
- *
- * @template $Data - The data type being masked
- */
-export type Mask<$Data = any> = BinaryMask<$Data> | PropertiesMask<$Data extends object ? $Data : object>
-
-/**
- * Create a mask based on the provided options.
- *
- * @param options - Mask configuration:
- *   - `boolean`: Creates a binary mask (true = show, false = hide)
- *   - `string[]`: Creates a properties mask that allows only the specified keys
- *   - `object`: Creates a properties mask based on true/false values per key
- *
- * @returns A mask that can be applied to data
- *
- * @example
- * ```ts
- * // Binary mask
- * const showAll = create(true)
- * const hideAll = create(false)
- *
- * // Properties mask with array
- * const allowMask = create<User>(['name', 'email'])
- *
- * // Properties mask with object
- * const objectMask = create<User>({
- *   name: true,
- *   email: true,
- *   password: false
- * })
- * ```
- */
-export const create = <$Data = unknown>(
-  options: InferOptions<$Data>,
-): Mask<$Data> => {
-  if (typeof options === 'boolean') {
-    return createBinary(options) as any
-  }
-
-  // Array input -> PropertiesMask with 'allow' mode
-  if (Array.isArray(options)) {
-    return createProperties('allow', options as any) as any
-  }
-
-  // Object input -> PropertiesMask based on true/false values
-  const entries = Object.entries(options)
-
-  const allowedKeys = entries
-    .filter(([_, include]) => include === true)
-    .map(([key]) => key)
-
-  const deniedKeys = entries
-    .filter(([_, include]) => include === false)
-    .map(([key]) => key)
-
-  // If we have denied keys, use deny mode
-  if (deniedKeys.length > 0 && allowedKeys.length === 0) {
-    return createProperties('deny', deniedKeys) as any
-  }
-
-  // Default to allow mode with allowed keys
-  return createProperties('allow', allowedKeys) as any
-}
-
-/**
- * Valid options for creating a mask for the given data type.
- *
- * @template $Data - The data type to be masked
- */
-export type InferOptions<$Data> = unknown extends $Data ? boolean | string[] | Record<string, boolean>
-  : $Data extends object ? (
-      | boolean
-      | (keyof $Data)[]
-      | Partial<
-        {
-          [K in keyof $Data]: boolean
-        }
-      >
-    )
-  : boolean
-
-//
-//
-//
-//
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • PropertiesMask
-//
-//
-
-/**
- * A mask that selectively shows or hides object properties.
- *
- * @template $Data - The object type being masked
- */
-export interface PropertiesMask<$Data extends object = object> {
-  type: 'properties'
-  /** Whether to allow only specified properties or deny them */
-  mode: 'allow' | 'deny'
-  /** The list of property keys to allow or deny */
-  properties: (keyof $Data)[]
-}
-
-/**
- * Create a properties mask.
- *
- * @param mode - 'allow' to show only specified properties, 'deny' to hide them
- * @param properties - Array of property keys to allow or deny
- * @returns A PropertiesMask
- */
-export const createProperties = <$Data extends object = object>(
-  mode: 'allow' | 'deny',
-  properties: (keyof $Data)[],
-): PropertiesMask<$Data> => ({
-  type: 'properties',
-  mode,
-  properties,
-})
-
-//
-//
-//
-//
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • BinaryMask
-//
-//
-
-/**
- * A mask that either shows or hides data entirely.
- *
- * @template _$Data - The data type being masked (used for type inference)
- */
-export type BinaryMask<_$Data = any> = {
-  type: 'binary'
-  /** Whether to show (true) or hide (false) the data */
-  show: boolean
-}
-
-/**
- * Create a binary mask.
- *
- * @param show - Whether to show (true) or hide (false) the data
- * @returns A BinaryMask
- */
-export const createBinary = <$Data = any>(show: boolean): BinaryMask<$Data> => ({
-  type: 'binary',
-  show,
-})
-
-//
-//
-//
-//
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Convenience Constructors with Semantic Names
-//
-//
-
-/**
- * Create a mask that shows all data.
- * @returns A BinaryMask with show=true
- */
-export const show = (): BinaryMask => ({
-  type: 'binary',
-  show: true,
-})
-
-/**
- * Create a mask that hides all data.
- * @returns A BinaryMask with show=false
- */
-export const hide = (): BinaryMask => ({
-  type: 'binary',
-  show: false,
-})
-
-/**
- * Create a mask that shows only the specified properties.
- *
- * @param properties - Array of property keys to show
- * @returns A PropertiesMask in 'allow' mode
- *
- * @example
- * ```ts
- * const userMask = pick<User>(['name', 'email'])
- * // Only 'name' and 'email' will be shown
- * ```
- */
-export const pick = <$Data extends object = object>(
-  properties: (keyof $Data)[],
-): PropertiesMask<$Data> => ({
-  type: 'properties',
-  mode: 'allow',
-  properties,
-})
-
-/**
- * Create a mask that hides the specified properties.
- *
- * @param properties - Array of property keys to hide
- * @returns A PropertiesMask in 'deny' mode
- *
- * @example
- * ```ts
- * const userMask = omit<User>(['password', 'ssn'])
- * // Everything except 'password' and 'ssn' will be shown
- * ```
- */
-export const omit = <$Data extends object = object>(
-  properties: (keyof $Data)[],
-): PropertiesMask<$Data> => ({
-  type: 'properties',
-  mode: 'deny',
-  properties,
-})
-
-//
-//
-//
-//
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Utilities
-//
-//
-
-/**
- * Extract the data type from a mask.
- *
- * @template $Mask - The mask type
- * @returns The data type the mask is designed for
- */
-// dprint-ignore
-export type GetDataType<$Mask extends Mask<any>> =
-  $Mask extends BinaryMask<infer $Data>     ? $Data :
-  $Mask extends PropertiesMask<infer $Data> ? $Data
-                                            : never

package/src/lib/task/$$.ts

@@ -1,2 +0,0 @@
-export * from './report.ts'
-export * from './task.ts'

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

@@ -1,209 +0,0 @@
-import * as fc from 'fast-check'
-import { describe, expect, test, vi } from 'vitest'
-import { Task } from './$.ts'
-
-describe('create', () => {
-  test('executes async function and captures timing', async () => {
-    const double = Task.create(
-      async (x: number) => x * 2,
-      { name: 'double' },
-    )
-
-    const report = await double(5)
-
-    expect(report.task.name).toBe('double')
-    expect(report.execution.input).toBe(5)
-    expect(report.execution.output).toBe(10)
-    expect(report.execution.timings.duration).toBeGreaterThan(0)
-  })
-
-  test('captures errors', async () => {
-    const failing = Task.create(
-      async () => {
-        throw new Error('Failed')
-      },
-      { name: 'failing' },
-    )
-
-    const report = await failing(null)
-
-    expect(report.execution.output).toBeInstanceOf(Error)
-    expect((report.execution.output as Error).message).toBe('Failed')
-  })
-})
-
-describe('formatReport', () => {
-  test('masks sensitive data', async () => {
-    const createUser = Task.create(
-      async (data: any) => ({
-        email: data.email,
-        token: 'abc123',
-      }),
-      {
-        name: 'create-user',
-        mask: {
-          input: { password: false }, // Hide password
-          output: { token: false }, // Hide token
-        },
-      },
-    )
-
-    const report = await createUser({
-      email: 'user@example.com',
-      password: 'secret',
-    })
-
-    // Uses mask from task definition by default
-    const formatted = Task.formatReport(report)
-
-    expect(formatted).toContain('create-user')
-    expect(formatted).toContain('user@example.com')
-    expect(formatted).not.toContain('secret')
-    expect(formatted).not.toContain('abc123')
-  })
-
-  test('debug mode reveals all data', async () => {
-    const createUser = Task.create(
-      async (data: any) => ({
-        email: data.email,
-        token: 'abc123',
-      }),
-      {
-        name: 'create-user',
-        mask: {
-          input: { password: false }, // Hide password
-          output: { token: false }, // Hide token
-        },
-      },
-    )
-
-    const report = await createUser({
-      email: 'user@example.com',
-      password: 'secret',
-    })
-
-    const formatted = Task.formatReport(report, { debug: true })
-
-    expect(formatted).toContain('secret')
-    expect(formatted).toContain('abc123')
-  })
-})
-
-describe('exitWithReport', () => {
-  test('exits with code 0 on success', async () => {
-    const mockExit = vi.spyOn(process, 'exit').mockImplementation(() => {
-      throw new Error('process.exit called')
-    })
-    const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
-
-    const success = Task.create(async () => 'result')
-    const report = await success(null)
-
-    expect(() => Task.exitWithReport(report)).toThrow('process.exit called')
-    expect(mockExit).toHaveBeenCalledWith(0)
-    expect(mockLog).toHaveBeenCalled()
-
-    mockExit.mockRestore()
-    mockLog.mockRestore()
-  })
-
-  test('exits with code 1 on error', async () => {
-    const mockExit = vi.spyOn(process, 'exit').mockImplementation(() => {
-      throw new Error('process.exit called')
-    })
-    const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
-
-    const failing = Task.create(async () => {
-      throw new Error('Failed')
-    })
-    const report = await failing(null)
-
-    expect(() => Task.exitWithReport(report)).toThrow('process.exit called')
-    expect(mockExit).toHaveBeenCalledWith(1)
-    expect(mockLog).toHaveBeenCalled()
-
-    mockExit.mockRestore()
-    mockLog.mockRestore()
-  })
-})
-
-describe('runAndExit', () => {
-  test('combines create, execute, and exit into one call', async () => {
-    const mockExit = vi.spyOn(process, 'exit').mockImplementation(() => {
-      throw new Error('process.exit called')
-    })
-    const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
-
-    const double = async (x: number) => x * 2
-
-    await expect(() => Task.runAndExit(double, 5, { name: 'double' })).rejects.toThrow('process.exit called')
-
-    expect(mockExit).toHaveBeenCalledWith(0)
-    expect(mockLog).toHaveBeenCalled()
-
-    // Verify the logged output contains expected content
-    const loggedOutput = mockLog.mock.calls[0]?.[0]
-    expect(loggedOutput).toContain('double')
-    expect(loggedOutput).toContain('10') // Result of 5 * 2
-
-    mockExit.mockRestore()
-    mockLog.mockRestore()
-  })
-
-  test('exits with error code on failure', async () => {
-    const mockExit = vi.spyOn(process, 'exit').mockImplementation(() => {
-      throw new Error('process.exit called')
-    })
-    const mockLog = vi.spyOn(console, 'log').mockImplementation(() => {})
-
-    const failing = async () => {
-      throw new Error('Task failed')
-    }
-
-    await expect(() => Task.runAndExit(failing, null, { name: 'failing' })).rejects.toThrow('process.exit called')
-
-    expect(mockExit).toHaveBeenCalledWith(1)
-    expect(mockLog).toHaveBeenCalled()
-
-    mockExit.mockRestore()
-    mockLog.mockRestore()
-  })
-})
-
-describe('property-based tests', () => {
-  test('duration is always positive', async () => {
-    await fc.assert(
-      fc.asyncProperty(
-        fc.integer(),
-        async (input) => {
-          const identity = Task.create(
-            async (x: any) => x,
-            { name: 'identity' },
-          )
-
-          const report = await identity(input)
-
-          expect(report.execution.timings.duration).toBeGreaterThanOrEqual(0)
-          expect(report.execution.output).toBe(input)
-        },
-      ),
-    )
-  })
-
-  test('timing fields are consistent', async () => {
-    await fc.assert(
-      fc.asyncProperty(
-        fc.anything(),
-        async (input) => {
-          const noop = Task.create(async (_: any) => null)
-          const report = await noop(input)
-
-          const { start, end, duration } = report.execution.timings
-
-          expect(end).toBeGreaterThanOrEqual(start)
-          expect(duration).toBeCloseTo(end - start, 5)
-        },
-      ),
-    )
-  })
-})

package/src/lib/task/$.ts

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

package/src/lib/task/report.ts

@@ -1,72 +0,0 @@
-import { Mask } from '#lib/mask'
-import { Err, Str } from '@wollybeard/kit'
-import type { Definition, MaskOptions } from './task.ts'
-
-export interface Report<$Input, $Output> {
-  task: Definition<$Input, $Output>
-  execution: {
-    input: $Input
-    output: $Output | Error
-    timings: {
-      start: number
-      end: number
-      duration: number
-    }
-  }
-}
-
-export interface FormatOptions<$Input, $Output> {
-  /**
-   * Force masks to reveal all data
-   */
-  debug?: boolean
-  /**
-   * A mask to apply to the input (if any) and successful return (if any).
-   *
-   * @default Uses the mask bundled with the task, if any.
-   */
-  mask?: MaskOptions<$Input, $Output>
-}
-
-export const formatReport = <$Input, $Output>(
-  report: Report<$Input, $Output>,
-  options?: FormatOptions<$Input, $Output>,
-): string => {
-  const maskOptions = options?.debug
-    ? undefined
-    : (options?.mask ?? report.task.mask)
-
-  // Apply masks
-  const maskedInput = maskOptions?.input
-    ? Mask.apply(report.execution.input, Mask.create(maskOptions.input))
-    : report.execution.input
-
-  const maskedOutput = report.execution.output instanceof Error || !maskOptions?.output
-    ? report.execution.output
-    : Mask.apply(report.execution.output, Mask.create(maskOptions.output))
-
-  // Format report
-  const s = Str.Builder()
-
-  s`Task: ${report.task.name}`
-  s`Duration: ${report.execution.timings.duration.toFixed(2)}ms`
-  s`Input: ${JSON.stringify(maskedInput, null, 2)}`
-
-  if (report.execution.output instanceof Error) {
-    s(Err.inspect(report.execution.output))
-  } else {
-    s`Output: ${JSON.stringify(maskedOutput, null, 2)}`
-  }
-
-  return s.render()
-}
-
-export const exitWithReport = <$Input, $Output>(
-  report: Report<$Input, $Output>,
-  options?: FormatOptions<$Input, $Output>,
-): never => {
-  const isError = Err.is(report.execution.output)
-  const exitCode = isError ? 1 : 0
-  console.log(formatReport(report, options))
-  process.exit(exitCode)
-}