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

package/src/lib/mask/mask.ts

@@ -0,0 +1,244 @@
+//
+//
+//
+//
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • 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/shiki/shiki.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from 'vitest'
-import { getHighlighter, highlightCode } from './shiki.js'
+import { getHighlighter, highlightCode } from './shiki.ts'
 
 test(`getHighlighter returns singleton instance`, async () => {
   const highlighter1 = await getHighlighter()

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

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

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

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

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

package/src/lib/task/report.ts

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

package/src/lib/task/task.ts

@@ -0,0 +1,112 @@
+import type { Mask } from '#lib/mask'
+import type { Report } from './report.ts'
+import { exitWithReport } from './report.ts'
+
+export interface Definition<$Input = any, $Output = any> {
+  name: string
+  mask?: MaskOptions<$Input, $Output>
+}
+
+export interface Task<$Input, $Output> {
+  (input: $Input): Promise<Report<$Input, $Output>>
+  definition: Definition<$Input, $Output>
+}
+
+export interface MaskOptions<$Input, $Output> {
+  /**
+   * @default true
+   */
+  input?: Mask.InferOptions<$Input>
+  /**
+   * @default true
+   */
+  output?: Mask.InferOptions<$Output>
+}
+
+export const create = <$Input, $Output>(
+  fn: (input: $Input) => Promise<$Output>,
+  options?: {
+    /**
+     * @default the fn name
+     */
+    name?: string
+    /**
+     * An optional default mask to use for successfully returned values.
+     */
+    mask?: MaskOptions<$Input, $Output>
+  },
+): Task<$Input, $Output> => {
+  const definition: Definition<$Input, $Output> = {
+    name: options?.name ?? (fn.name || 'anonymous'),
+    mask: options?.mask,
+  }
+
+  const task = async (input: $Input): Promise<Report<$Input, $Output>> => {
+    const start = performance.now()
+
+    try {
+      const output = await fn(input)
+      const end = performance.now()
+
+      return {
+        task: definition,
+        execution: {
+          input,
+          output,
+          timings: {
+            start,
+            end,
+            duration: end - start,
+          },
+        },
+      }
+    } catch (error) {
+      const end = performance.now()
+
+      return {
+        task: definition,
+        execution: {
+          input,
+          output: error as Error,
+          timings: {
+            start,
+            end,
+            duration: end - start,
+          },
+        },
+      }
+    }
+  }
+
+  task.definition = definition
+
+  return task
+}
+
+/**
+ * Sugar method that creates a task, executes it, and exits with the report.
+ * Equivalent to: create(fn, options) -> task(input) -> exitWithReport(report)
+ *
+ * @param fn - The function to wrap as a task
+ * @param input - Input to pass to the task
+ * @param options - Combined task creation and format options
+ */
+export const runAndExit = async <$Input, $Output>(
+  fn: (input: $Input) => Promise<$Output>,
+  input: $Input,
+  options?: {
+    name?: string
+    mask?: MaskOptions<$Input, $Output>
+    debug?: boolean
+  },
+): Promise<never> => {
+  const task = create(fn, {
+    name: options?.name,
+    mask: options?.mask,
+  })
+  const report = await task(input)
+  return exitWithReport(report, {
+    debug: options?.debug,
+    mask: options?.mask,
+  })
+}