npm - polen - Versions diffs - 0.10.0-next.14 → 0.10.0-next.16 - Mend

polen 0.10.0-next.14 → 0.10.0-next.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1108) hide show

package/src/lib/html-utils/inject-global-data.test.ts ADDED Viewed

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import {
+  createGlobalDataScript,
+  createGlobalDataScriptWithInit,
+  injectGlobalDataIntoHTML,
+} from './inject-global-data.js'
+describe('createGlobalDataScript', () => {
+  it('creates a script tag with JSON data', () => {
+    const result = createGlobalDataScript('__TEST__', { foo: 'bar', num: 42 })
+    expect(result).toBe('<script>globalThis.__TEST__ = {"foo":"bar","num":42};</script>')
+  })
+  it('handles nested data structures', () => {
+    const data = {
+      user: { id: 1, name: 'John' },
+      settings: { theme: 'dark', notifications: true },
+    }
+    const result = createGlobalDataScript('__APP__', data)
+    expect(result).toContain('globalThis.__APP__ =')
+    expect(result).toContain(JSON.stringify(data))
+  })
+  it('escapes special characters in data', () => {
+    const data = { html: '</script><script>alert("xss")</script>' }
+    const result = createGlobalDataScript('__SAFE__', data)
+    // JSON.stringify escapes the forward slashes
+    expect(result).not.toContain('</script><script>')
+    expect(result).toContain('<\\/script>')
+  })
+  it('throws on invalid global names', () => {
+    expect(() => createGlobalDataScript('123invalid', {})).toThrow('Invalid global variable name')
+    expect(() => createGlobalDataScript('invalid-name', {})).toThrow('Invalid global variable name')
+    expect(() => createGlobalDataScript('invalid.name', {})).toThrow('Invalid global variable name')
+  })
+  it('accepts valid global names', () => {
+    expect(() => createGlobalDataScript('_valid', {})).not.toThrow()
+    expect(() => createGlobalDataScript('$valid', {})).not.toThrow()
+    expect(() => createGlobalDataScript('VALID_123', {})).not.toThrow()
+  })
+})
+describe('createGlobalDataScriptWithInit', () => {
+  it('creates script with data and init code', () => {
+    const result = createGlobalDataScriptWithInit(
+      '__THEME__',
+      { theme: 'dark' },
+      'document.body.className = globalThis.__THEME__.theme;',
+    )
+    expect(result).toContain('globalThis.__THEME__ = {"theme":"dark"};')
+    expect(result).toContain('document.body.className = globalThis.__THEME__.theme;')
+    expect(result).toMatch(/<script>.*<\/script>/s)
+  })
+  it('returns just data script when no init code provided', () => {
+    const result = createGlobalDataScriptWithInit('__TEST__', { foo: 'bar' })
+    expect(result).toBe('<script>globalThis.__TEST__ = {"foo":"bar"};</script>')
+  })
+})
+describe('injectGlobalDataIntoHTML', () => {
+  const sampleHTML = `
+<html>
+  <head>
+    <title>Test</title>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>`
+  it('injects script into head', () => {
+    const result = injectGlobalDataIntoHTML(sampleHTML, '__APP__', { version: '1.0' })
+    expect(result).toContain('<head>\n<script>globalThis.__APP__ = {"version":"1.0"};</script>')
+  })
+  it('injects script with init code', () => {
+    const result = injectGlobalDataIntoHTML(
+      sampleHTML,
+      '__CONFIG__',
+      { apiUrl: '/api' },
+      'console.log("Config loaded:", globalThis.__CONFIG__);',
+    )
+    expect(result).toContain('globalThis.__CONFIG__ = {"apiUrl":"/api"};')
+    expect(result).toContain('console.log("Config loaded:", globalThis.__CONFIG__);')
+  })
+})

package/src/lib/html-utils/inject-global-data.ts ADDED Viewed

@@ -0,0 +1,80 @@
+/**
+ * Creates an HTML script tag that injects data into a global variable
+ *
+ * @param globalName - The name of the global variable (e.g., '__POLEN__')
+ * @param data - The data to inject (will be JSON stringified)
+ * @returns HTML script tag string ready to inject into HTML
+ *
+ * @example
+ * ```ts
+ * const script = createGlobalDataScript('__MY_APP__', { user: { id: 1, name: 'John' } })
+ * // Returns: <script>globalThis.__MY_APP__ = {"user":{"id":1,"name":"John"}};</script>
+ * ```
+ */
+export const createGlobalDataScript = (globalName: string, data: unknown): string => {
+  // Validate global name to prevent injection attacks
+  if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(globalName)) {
+    throw new Error(`Invalid global variable name: ${globalName}`)
+  }
+  // JSON.stringify and then escape </script> tags to prevent XSS
+  const jsonData = JSON.stringify(data)
+    // Escape </script> to prevent breaking out of script tag
+    .replace(/<\/script>/gi, '<\\/script>')
+  return `<script>globalThis.${globalName} = ${jsonData};</script>`
+}
+/**
+ * Creates a script tag that initializes global data and runs initialization code
+ *
+ * @param globalName - The name of the global variable
+ * @param data - The data to inject
+ * @param initCode - Optional initialization code to run after setting the global
+ * @returns HTML script tag string
+ *
+ * @example
+ * ```ts
+ * const script = createGlobalDataScriptWithInit('__THEME__', { theme: 'dark' }, `
+ *   document.documentElement.className = globalThis.__THEME__.theme;
+ * `)
+ * ```
+ */
+export const createGlobalDataScriptWithInit = (
+  globalName: string,
+  data: unknown,
+  initCode?: string,
+): string => {
+  const dataScript = createGlobalDataScript(globalName, data)
+  if (!initCode) {
+    return dataScript
+  }
+  // Remove the closing </script> tag from data script and append init code
+  const scriptContent = dataScript.replace('</script>', `\n${initCode}\n</script>`)
+  return scriptContent
+}
+/**
+ * Injects a global data script into the head of an HTML document
+ *
+ * @param html - The HTML document string
+ * @param globalName - The name of the global variable
+ * @param data - The data to inject
+ * @param initCode - Optional initialization code
+ * @returns Modified HTML with script injected
+ */
+export const injectGlobalDataIntoHTML = (
+  html: string,
+  globalName: string,
+  data: unknown,
+  initCode?: string,
+): string => {
+  const script = initCode
+    ? createGlobalDataScriptWithInit(globalName, data, initCode)
+    : createGlobalDataScript(globalName, data)
+  // Inject at the beginning of head to ensure it runs first
+  return html.replace('<head>', `<head>\n${script}`)
+}

package/src/lib/kit-temp.test-d.ts CHANGED Viewed

@@ -3,24 +3,29 @@ import { objFilter, ObjOmit, ObjPick, objPolicyFilter } from './kit-temp.js'
 import type { ObjPolicyFilter } from './kit-temp.js'
 // Test object for all tests
-type TestObj = { a: string; b: number; c: boolean; d: string[] }
+interface TestObj {
+  a: string
+  b: number
+  c: boolean
+  d: string[]
+}
 declare const testObj: TestObj
 // Test 1: objPolicyFilter with allow mode
 {
-  const result = objPolicyFilter('allow', testObj, ['a', 'c'] as const)
+  const result = objPolicyFilter(`allow`, testObj, [`a`, `c`] as const)
   Ts.assertEqual<{ a: string; c: boolean }>()(result)
 }
 // Test 2: objPolicyFilter with deny mode
 {
-  const result = objPolicyFilter('deny', testObj, ['a', 'c'] as const)
+  const result = objPolicyFilter(`deny`, testObj, [`a`, `c`] as const)
   Ts.assertEqual<{ b: number; d: string[] }>()(result)
 }
 // Test 3: objFilter returns Partial<T>
 {
-  const result = objFilter(testObj, (key, value) => value !== 'hello')
+  const result = objFilter(testObj, (key, value) => value !== `hello`)
   Ts.assertEqual<Partial<TestObj>>()(result)
   // All properties are optional
@@ -32,28 +37,28 @@ declare const testObj: TestObj
 // Test 4: ObjPick type inference
 {
-  const result = ObjPick(testObj, ['a', 'c'] as const)
+  const result = ObjPick(testObj, [`a`, `c`] as const)
   Ts.assertEqual<{ a: string; c: boolean }>()(result)
 }
 // Test 5: ObjOmit type inference
 {
-  const result = ObjOmit(testObj, ['a', 'c'] as const)
+  const result = ObjOmit(testObj, [`a`, `c`] as const)
   Ts.assertEqual<{ b: number; d: string[] }>()(result)
 }
 // Test 6: ObjPolicyFilter type-level function
 {
-  type Allow = ObjPolicyFilter<TestObj, 'a' | 'c', 'allow'>
+  type Allow = ObjPolicyFilter<TestObj, `a` | `c`, `allow`>
   type _TestAllow = Ts.AssertEqual<Allow, { a: string; c: boolean }>
-  type Deny = ObjPolicyFilter<TestObj, 'a' | 'c', 'deny'>
+  type Deny = ObjPolicyFilter<TestObj, `a` | `c`, `deny`>
   type _TestDeny = Ts.AssertEqual<Deny, { b: number; d: string[] }>
-  type AllowEmpty = ObjPolicyFilter<TestObj, never, 'allow'>
+  type AllowEmpty = ObjPolicyFilter<TestObj, never, `allow`>
   type _TestAllowEmpty = Ts.AssertEqual<AllowEmpty, {}>
-  type DenyEmpty = ObjPolicyFilter<TestObj, never, 'deny'>
+  type DenyEmpty = ObjPolicyFilter<TestObj, never, `deny`>
   type _TestDenyEmpty = Ts.AssertEqual<DenyEmpty, TestObj>
 }
@@ -61,8 +66,8 @@ declare const testObj: TestObj
 {
   // Empty object
   const empty = {}
-  const allowEmpty = objPolicyFilter('allow', empty, [])
-  const denyEmpty = objPolicyFilter('deny', empty, [])
+  const allowEmpty = objPolicyFilter(`allow`, empty, [])
+  const denyEmpty = objPolicyFilter(`deny`, empty, [])
   const filterEmpty = objFilter(empty, () => true)
   Ts.assertEqual<{}>()(allowEmpty)
@@ -71,8 +76,8 @@ declare const testObj: TestObj
   // Single property object
   const single = { a: 1 }
-  const allowSingle = objPolicyFilter('allow', single, ['a'] as const)
-  const denySingle = objPolicyFilter('deny', single, ['a'] as const)
+  const allowSingle = objPolicyFilter(`allow`, single, [`a`] as const)
+  const denySingle = objPolicyFilter(`deny`, single, [`a`] as const)
   const filterSingle = objFilter(single, () => true)
   Ts.assertEqual<{ a: number }>()(allowSingle)
@@ -82,7 +87,7 @@ declare const testObj: TestObj
 // Test 8: Complex nested object
 {
-  type ComplexObj = {
+  interface ComplexObj {
     nested: { a: string; b: number }
     array: string[]
     optional?: boolean
@@ -90,26 +95,26 @@ declare const testObj: TestObj
   }
   const complexObj = {} as ComplexObj
-  const picked = objPolicyFilter('allow', complexObj, ['nested', 'optional'] as const)
+  const picked = objPolicyFilter(`allow`, complexObj, [`nested`, `optional`] as const)
   Ts.assertEqual<{ nested: { a: string; b: number }; optional?: boolean }>()(picked)
-  const omitted = objPolicyFilter('deny', complexObj, ['nested', 'optional'] as const)
+  const omitted = objPolicyFilter(`deny`, complexObj, [`nested`, `optional`] as const)
   Ts.assertEqual<{ array: string[]; readonly ro: string }>()(omitted)
-  const filtered = objFilter(complexObj, (key) => key !== 'array')
+  const filtered = objFilter(complexObj, (key) => key !== `array`)
   Ts.assertEqual<Partial<ComplexObj>>()(filtered)
 }
 // Test 9: Keys parameter type inference
 {
   // With const assertion
-  const keys1 = ['a', 'c'] as const
-  const result1 = objPolicyFilter('allow', testObj, keys1)
+  const keys1 = [`a`, `c`] as const
+  const result1 = objPolicyFilter(`allow`, testObj, keys1)
   Ts.assertEqual<{ a: string; c: boolean }>()(result1)
   // Without const assertion (wider type)
-  const keys2: (keyof TestObj)[] = ['a', 'c']
-  const result2 = objPolicyFilter('allow', testObj, keys2)
+  const keys2: (keyof TestObj)[] = [`a`, `c`]
+  const result2 = objPolicyFilter(`allow`, testObj, keys2)
   // Result is a union of all possible picks
   type Result2 = typeof result2 // Pick<TestObj, keyof TestObj>
 }

package/src/lib/kit-temp.test.ts CHANGED Viewed

@@ -76,10 +76,10 @@ describe('property-based tests', () => {
           // Combined they reconstruct the original object (only own properties)
           const reconstructed = { ...allowed, ...denied }
-          const ownPropsObj = Object.keys(obj).reduce((acc, key) => {
+          const ownPropsObj = Object.keys(obj).reduce<any>((acc, key) => {
             acc[key] = obj[key]
             return acc
-          }, {} as any)
+          }, {})
           expect(reconstructed).toEqual(ownPropsObj)
         },
       ),
@@ -94,10 +94,10 @@ describe('property-based tests', () => {
           const filtered = objFilter(obj, () => true)
           // Object.keys doesn't include __proto__, so we need to handle it specially
-          const objWithoutProto = Object.keys(obj).reduce((acc, key) => {
+          const objWithoutProto = Object.keys(obj).reduce<any>((acc, key) => {
             acc[key] = obj[key]
             return acc
-          }, {} as any)
+          }, {})
           expect(filtered).toEqual(objWithoutProto)

package/src/lib/kit-temp.ts CHANGED Viewed

@@ -64,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>>
@@ -96,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 (Object.prototype.hasOwnProperty.call(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>(
@@ -233,7 +233,7 @@ export type ExtendsExact<$Input, $Constraint> =
  * ```
  */
 export const chunk = <T>(array: readonly T[], size: number): T[][] => {
-  if (size <= 0) throw new Error('Chunk size must be greater than 0')
+  if (size <= 0) throw new Error(`Chunk size must be greater than 0`)
   if (array.length === 0) return []
   const chunks: T[][] = []
@@ -345,7 +345,7 @@ const processBatch = async <T, R>(
   operation: (item: T, index: number) => Promise<R>,
   concurrency: number,
   failFast: boolean,
-  startIndex: number = 0,
+  startIndex = 0,
 ): Promise<AsyncParallelResult<T, R>> => {
   const results: R[] = []
   const errors: (Error & { item: T })[] = []
@@ -372,7 +372,7 @@ const processBatch = async <T, R>(
     const chunkResults = await Promise.allSettled(promises)
     for (const promiseResult of chunkResults) {
-      if (promiseResult.status === 'fulfilled') {
+      if (promiseResult.status === `fulfilled`) {
         const { success, result, error, item } = promiseResult.value
         if (success) {
           results.push(result!)
@@ -385,7 +385,7 @@ const processBatch = async <T, R>(
       } 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 }
+        const error = new Error(`Unexpected promise rejection`) as Error & { item: any }
         errors.push(error)
         if (failFast) {
           return { results, errors, success: false }
@@ -520,3 +520,75 @@ export const asyncReduceWith = <T, C>(
     )
   }
 }
+/**
+ * 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>
+}

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/src/lib/mask/apply.ts CHANGED Viewed

@@ -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)