improvement(utils): add toArray and the scalar payload coercions (#8055)

* improvement(utils): add toArray and the scalar coercions, replacing 44 copies

Ten files declared `Array.isArray(v) ? v : []` and 34 declared the
`typeof v === 'x' ? v : null` one-liner under eleven different names.

* docs: document toArray and the scalar payload coercions

Author: waleedlatif1

.claude/rules/global.md

@@ -52,6 +52,8 @@ Use shared helpers from `@sim/utils` instead of writing inline implementations:
 - `omit(obj, keys)` from `@sim/utils/object` — remove keys from object
 - `filterUndefined(obj)` from `@sim/utils/object` — strip undefined-valued keys. Never write `Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))`
 - `isRecordLike(value)` from `@sim/utils/object` — indexable-object guard. Never redeclare `typeof value === 'object' && value !== null && !Array.isArray(value)`
+- `toRecord(value)` / `toRecordOrNull(value)` / `toArray(value)` from `@sim/utils/object` — coerce an untyped payload value to a record or array. Never inline `isRecordLike(v) ? v : {}` or `Array.isArray(v) ? v : []`. Where the source is already typed, keep the inline `Array.isArray` check: it narrows, while `toArray` asserts
+- `toStringOrNull(value)` / `toNumberOrNull(value)` / `toBooleanOrNull(value)` from `@sim/utils/coerce` — read one scalar out of an untyped payload. Never declare a local one-liner that is byte-identical to one of these (`asString`, `getString`, `nullableString`, …). Keep a local helper that differs: one returning `undefined` rather than `null` changes the wire shape, and one adding `Number.isFinite` or a string parse is a stricter check these deliberately omit
 - `truncate(str, maxLength, suffix?)` from `@sim/utils/string` — safe string truncation with ellipsis
 - `escapeRegExp(value)` from `@sim/utils/string` — escape regex metacharacters. Never inline `replace(/[.*+?^${}()|[\]\\]/g, '\\$&')`
 - `compareStrings(left, right)` from `@sim/utils/string` — code-unit string comparator for hashes, fingerprints, and values compared across processes. Never `localeCompare` there

.cursor/rules/global.mdc

@@ -55,6 +55,8 @@ Use shared helpers from `@sim/utils` instead of writing inline implementations:
 - `omit(obj, keys)` from `@sim/utils/object` — remove keys from object
 - `filterUndefined(obj)` from `@sim/utils/object` — strip undefined-valued keys. Never write `Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))`
 - `isRecordLike(value)` from `@sim/utils/object` — indexable-object guard. Never redeclare `typeof value === 'object' && value !== null && !Array.isArray(value)`
+- `toRecord(value)` / `toRecordOrNull(value)` / `toArray(value)` from `@sim/utils/object` — coerce an untyped payload value to a record or array. Never inline `isRecordLike(v) ? v : {}` or `Array.isArray(v) ? v : []`. Where the source is already typed, keep the inline `Array.isArray` check: it narrows, while `toArray` asserts
+- `toStringOrNull(value)` / `toNumberOrNull(value)` / `toBooleanOrNull(value)` from `@sim/utils/coerce` — read one scalar out of an untyped payload. Never declare a local one-liner that is byte-identical to one of these (`asString`, `getString`, `nullableString`, …). Keep a local helper that differs: one returning `undefined` rather than `null` changes the wire shape, and one adding `Number.isFinite` or a string parse is a stricter check these deliberately omit
 - `truncate(str, maxLength, suffix?)` from `@sim/utils/string` — safe string truncation with ellipsis
 - `escapeRegExp(value)` from `@sim/utils/string` — escape regex metacharacters. Never inline `replace(/[.*+?^${}()|[\]\\]/g, '\\$&')`
 - `compareStrings(left, right)` from `@sim/utils/string` — code-unit string comparator for hashes, fingerprints, and values compared across processes. Never `localeCompare` there

CLAUDE.md

@@ -17,6 +17,8 @@ You are a professional software engineer. All code must follow best practices: a
   - `structuredClone(value)` — built-in deep clone; never `JSON.parse(JSON.stringify(...))`
   - `omit(obj, keys)` / `filterUndefined(obj)` from `@sim/utils/object` — object trimming; never `Object.fromEntries(Object.entries(...).filter(...))`
   - `isRecordLike(value)` from `@sim/utils/object` — never redeclare `typeof value === 'object' && value !== null && !Array.isArray(value)`
+  - `toRecord(value)` / `toRecordOrNull(value)` / `toArray(value)` from `@sim/utils/object` — coerce an untyped payload value to a record or array; never inline `isRecordLike(v) ? v : {}` or `Array.isArray(v) ? v : []`. Where the source is already typed, keep the inline `Array.isArray` check: it narrows, while `toArray` asserts
+  - `toStringOrNull(value)` / `toNumberOrNull(value)` / `toBooleanOrNull(value)` from `@sim/utils/coerce` — read one scalar out of an untyped payload; never declare a local one-liner byte-identical to one of these. Keep a local helper that differs: `undefined` instead of `null` changes the wire shape, and a `Number.isFinite` or string-parse variant is a stricter check these omit
   - `truncate(str, maxLength, suffix?)` from `@sim/utils/string` — never inline slice + ellipsis
   - `escapeRegExp(value)` from `@sim/utils/string` — never inline `replace(/[.*+?^${}()|[\]\\]/g, '\\$&')`
   - `compareStrings(left, right)` from `@sim/utils/string` — code-unit ordering for hashes, fingerprints, and cross-process comparisons; never `localeCompare` there

apps/sim/app/api/v2/tables/utils.ts

@@ -1,3 +1,4 @@
+import { toStringOrNull } from '@sim/utils/coerce'
 import type {
   V2ApiTable,
   V2EnrichmentProviderOutcome,
@@ -238,11 +239,6 @@ function storedNumber(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0
 }
 
-/** Reads a stored field that the published shape declares as a nullable string. */
-function storedNullableString(value: unknown): string | null {
-  return typeof value === 'string' ? value : null
-}
-
 /**
  * Reads a stored timestamp, keeping only a value the published `date-time`
  * format will accept. A Postgres literal or a half-written blob becomes `null`
@@ -257,13 +253,13 @@ function storedTimestamp(value: unknown): string | null {
 function toApiEnrichmentProvider(value: unknown): V2EnrichmentProviderOutcome {
   const provider = (value ?? {}) as Record<string, unknown>
   return {
-    id: storedNullableString(provider.id) ?? '',
-    label: storedNullableString(provider.label) ?? '',
-    toolId: storedNullableString(provider.toolId) ?? '',
-    status: storedNullableString(provider.status) ?? 'not_run',
+    id: toStringOrNull(provider.id) ?? '',
+    label: toStringOrNull(provider.label) ?? '',
+    toolId: toStringOrNull(provider.toolId) ?? '',
+    status: toStringOrNull(provider.status) ?? 'not_run',
     cost: storedNumber(provider.cost),
     durationMs: storedNumber(provider.durationMs),
-    error: storedNullableString(provider.error),
+    error: toStringOrNull(provider.error),
   }
 }
 
@@ -287,7 +283,7 @@ export function toApiEnrichmentDetail(
     completedAt: storedTimestamp(stored.completedAt),
     durationMs: storedNumber(stored.durationMs),
     totalCost: storedNumber(stored.totalCost),
-    matchedProvider: storedNullableString(stored.matchedProvider),
+    matchedProvider: toStringOrNull(stored.matchedProvider),
     aborted: stored.aborted === true,
     providers: Array.isArray(stored.providers) ? stored.providers.map(toApiEnrichmentProvider) : [],
   }

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/utils.ts

@@ -1,3 +1,4 @@
+import { toArray } from '@sim/utils/object'
 /**
  * Extracts the raw value from a preview context entry.
  *
@@ -41,5 +42,5 @@ export function parseJsonArrayValue<T>(value: unknown): T[] {
       return []
     }
   }
-  return Array.isArray(parsed) ? (parsed as T[]) : []
+  return toArray<T>(parsed)
 }

apps/sim/connectors/grain/grain.ts

@@ -1,5 +1,6 @@
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
+import { toArray } from '@sim/utils/object'
 import { fetchWithRetry } from '@/lib/knowledge/documents/secure-fetch.server'
 import { VALIDATE_RETRY_OPTIONS } from '@/lib/knowledge/documents/utils'
 import { grainConnectorMeta } from '@/connectors/grain/meta'
@@ -328,7 +329,7 @@ async function fetchTranscript(
   }
 
   const data = await response.json()
-  return Array.isArray(data) ? (data as GrainTranscriptSegment[]) : []
+  return toArray<GrainTranscriptSegment>(data)
 }
 
 export const grainConnector: ConnectorConfig = {

apps/sim/lib/internal/asana/client.ts

@@ -1,3 +1,4 @@
+import { toArray } from '@sim/utils/object'
 import { readResponseTextWithLimit } from '@/lib/core/utils/stream-limits'
 import { AsanaOperationError } from '@/lib/internal/asana/errors'
 
@@ -13,7 +14,7 @@ export function asObject(value: unknown): AsanaJsonObject {
 }
 
 export function asArray(value: unknown): unknown[] {
-  return Array.isArray(value) ? value : []
+  return toArray(value)
 }
 
 function providerErrorMessage(response: Response, text: string): string {

apps/sim/lib/internal/cbinsights/operations/chat.ts

@@ -1,8 +1,8 @@
+import { toStringOrNull } from '@sim/utils/coerce'
 import type { InternalToolOperationImplementation } from '@/lib/internal/tool-operations/types'
 import type { CbInsightsChatParams } from '@/tools/cbinsights/chat'
 import {
   asArray,
-  asString,
   asStringArray,
   cbInsightsRequest,
   compactBody,
@@ -29,9 +29,9 @@ export const executeCbinsightsChatOperation: InternalToolOperationImplementation
       body: compactBody({ message, chatID: parseOptionalStringParam(params.chatId, 'chatId') }),
     },
     (data) => ({
-      chatId: asString(data.chatID),
-      title: asString(data.title),
-      message: asString(data.message),
+      chatId: toStringOrNull(data.chatID),
+      title: toStringOrNull(data.title),
+      message: toStringOrNull(data.message),
       sources: asArray(data.sources),
       relatedContent: asArray(data.relatedContent),
       suggestions: asStringArray(data.suggestions),

apps/sim/lib/internal/cbinsights/operations/get-exit-probability-history.ts

@@ -1,8 +1,8 @@
+import { toStringOrNull } from '@sim/utils/coerce'
 import type { InternalToolOperationImplementation } from '@/lib/internal/tool-operations/types'
 import type { CbInsightsExitProbabilityHistoryParams } from '@/tools/cbinsights/get_exit_probability_history'
 import {
   asArray,
-  asString,
   cbInsightsRequest,
   compactBody,
   parseOptionalStringParam,
@@ -25,7 +25,7 @@ export const executeCbinsightsGetExitProbabilityHistoryOperation: InternalToolOp
     (data) => ({
       ipo: asArray(data.ipo),
       mna: asArray(data.mna),
-      incompleteRoundType: asString(data.incompleteRoundType),
+      incompleteRoundType: toStringOrNull(data.incompleteRoundType),
     }),
     signal
   )

apps/sim/lib/internal/cbinsights/operations/get-org-funding-window.ts

@@ -1,7 +1,8 @@
+import { toNumberOrNull, toStringOrNull } from '@sim/utils/coerce'
 import { toRecordOrNull } from '@sim/utils/object'
 import type { InternalToolOperationImplementation } from '@/lib/internal/tool-operations/types'
 import type { CbInsightsOrgParams } from '@/tools/cbinsights/types'
-import { asNumber, asString, cbInsightsRequest, requireOrgId } from '@/tools/cbinsights/utils'
+import { cbInsightsRequest, requireOrgId } from '@/tools/cbinsights/utils'
 
 export const executeCbinsightsGetOrgFundingWindowOperation: InternalToolOperationImplementation<
   CbInsightsOrgParams
@@ -17,9 +18,9 @@ export const executeCbinsightsGetOrgFundingWindowOperation: InternalToolOperatio
     params,
     { path: `/v2/organizations/${orgId}/fundingwindow` },
     (data) => ({
-      windowStart: asString(data.windowStart),
-      windowEnd: asString(data.windowEnd),
-      cohortNextRoundRate: asNumber(data.cohortNextRoundRate),
+      windowStart: toStringOrNull(data.windowStart),
+      windowEnd: toStringOrNull(data.windowEnd),
+      cohortNextRoundRate: toNumberOrNull(data.cohortNextRoundRate),
       cohortCriteria: toRecordOrNull(data.cohortCriteria),
       latestFunding: toRecordOrNull(data.latestFunding),
     }),