refactor(utils): consolidate duplicated helpers onto @sim/utils

[waleedlatif1]

Summary

• Comprehensive audit of the repo for reimplementations of @sim/utils helpers (errors, id/random, retry, object, string, formatting) and fixed every genuine duplicate found.
• Wired check:utils (existing enforcement script, previously unused in CI) into test-build.yml so these patterns can't silently regress.

What changed

• Errors: error instanceof Error ? error.message : fallback → getErrorMessage(); manual .code === '23505' checks → getPostgresErrorCode() (19 files)
• Sleep / Math.random / retry: inline setTimeout promises → sleep(); Math.random() → randomFloat/randomInt/generateShortId(); apps/sim/tools/index.ts's local calculateBackoff/parseRetryAfterHeader → backoffWithJitter/parseRetryAfter (already importing sibling @sim/utils helpers in the same file)
• noop / object filtering: 8 duplicate const noop = () => {} → shared noop; Object.fromEntries(Object.entries(...).filter(...)) → filterUndefined/omit in packages/workflow-persistence, packages/logger (added as a new workspace dependency, zero circularity risk), and apps/sim/providers/utils.ts
• String truncation: 17 hand-rolled slice+ellipsis sites → truncate(), preserving exact visible output (two sites were unconditional before and are now correctly conditional — flagged as intentional behavior fixes)
• Date/time formatting: local getTimezoneAbbreviation/relative-time ladder/toLocaleDateString reimplementations (10 files, including two files with an identical copy-pasted helper) → getTimezoneAbbreviation/formatRelativeTime/formatDate/formatDateTime. A few of these are minor visible format changes (e.g. teammates/billing dates move from locale-dependent M/D/YYYY to fixed MMM D, YYYY) in exchange for one consistent format across the app.
• Email normalization: .trim().toLowerCase() → normalizeEmail() at 13+ call sites across auth/invite/billing flows
• Plain-object guards: local isRecord/isPlainObject reimplementations → isRecordLike() (7 sites)

Intentionally skipped (documented in code/PR, not silent): packages/ts-sdk and packages/cli (standalone published packages, already exempt in check-utils-enforcement.ts), packages/emcn's email handler (kept dependency-free by design), and a handful of lower-confidence tool-output/chart-axis date formatters that aren't generic UI dates.

Test plan

• bun run check:utils — passes (was previously failing with ~30 violations, never run in CI)
• bunx tsc --noEmit -p apps/sim/tsconfig.json — clean
• bunx biome check — clean
• bun run check:api-validation — passes
• All 13 directly-touched test files + tools/index.test.ts + providers/utils.test.ts + 5 more files with dedicated coverage — 443 tests passing

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 8, 2026 6:14pm

[cursor]

PR Summary

Medium Risk
Touches auth/email normalization, invite flows, tool HTTP retries, and schedule jitter—behavior should stay equivalent but spans many critical paths; minor visible date-format changes in some settings/billing UI.

Overview
Replaces scattered inline helpers across the monorepo with @sim/utils exports and adds bun run check:utils to the CI test-build workflow so duplicate patterns cannot regress.

Errors & DB: getErrorMessage, getPostgresErrorCode, and toError replace ad-hoc instanceof Error and .code === '23505' checks in API routes, blocks, copilot, and tooling.

Auth & email: Login, public file OTP/SSO, org invites, billing credits, deployment allow-lists, and related UI now use normalizeEmail() instead of repeated trim().toLowerCase().

Formatting & strings: Shared formatDate, formatDateTime, formatRelativeTime, and getTimezoneAbbreviation replace local date helpers; truncate() replaces hand-rolled slice+ellipsis in many UI and log paths (some invoice/teammate labels may shift from locale-specific to a fixed format).

Async & random: sleep(), noop, randomInt/randomFloat, generateShortId, and retry backoffWithJitter/parseRetryAfter replace local setTimeout promises, no-op lambdas, Math.random, and duplicate backoff logic in tools/index.ts and schedule jitter.

Object guards: isRecordLike, filterUndefined, and omit replace local plain-object checks and manual entry filtering; packages/logger gains a workspace dependency on @sim/utils for filterUndefined.

^{Reviewed by Cursor Bugbot for commit 3a06e25. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3a06e25. Configure here.}

[greptile-apps]

Greptile Summary

This PR is a comprehensive deduplication refactor across 93 files, consolidating hand-rolled helpers (error extraction, sleep/retry/backoff, string truncation, date/time formatting, email normalization, plain-object guards) onto the shared @sim/utils package, and wires the existing check:utils enforcement script into CI so these patterns can't silently reappear.

• Retry/backoff (tools/index.ts): local calculateBackoff/parseRetryAfterHeader replaced by backoffWithJitter/parseRetryAfter; the return-type change (number → number | null) is correctly handled at all three call sites with ?? 0 and explicit null checks.
• Date/time formatting: 10+ local relative-time and date formatters replaced by formatRelativeTime/formatDate/formatDateTime; a few visible format changes (e.g. "yesterday" → "1d ago", locale-dependent dates → fixed en-US MMM D, YYYY) are intentional and documented.
• Email, truncation, object filtering, record guards: normalizeEmail, truncate, filterUndefined/omit, and isRecordLike replace their respective inline reimplementations across auth, billing, logging, and persistence code.

Confidence Score: 4/5

Safe to merge; the one display-quality regression in schedule timezone labels for non-hardcoded IANA zones is cosmetic and does not affect data or workflow execution.

The vast majority of substitutions are mechanically correct and the retry/backoff rework in tools/index.ts handles the changed null-return contract properly at every call site. The only notable regression is in schedules/utils.ts: the deleted local getTimezoneAbbreviation resolved abbreviations for any IANA timezone via Intl.DateTimeFormat, while the replacement from @sim/utils hardcodes 9 zones and returns the raw IANA string for everything else — so users with timezones like Europe/Berlin or America/Toronto will see the full IANA name in schedule descriptions instead of a short abbreviation.

apps/sim/lib/workflows/schedules/utils.ts — the getTimezoneAbbreviation substitution degrades display quality for any IANA timezone not in the shared util's 9-entry hardcoded map

Important Files Changed

Filename	Overview
apps/sim/tools/index.ts	Replaces local calculateBackoff/parseRetryAfterHeader with shared backoffWithJitter/parseRetryAfter; null-return difference from parseRetryAfter correctly handled at all three call sites
apps/sim/lib/workflows/schedules/utils.ts	Removes local getTimezoneAbbreviation in favour of the shared util, which only covers 9 IANA timezones and falls back to raw IANA strings for all others — regression in schedule display quality
apps/sim/app/workspace/[workspaceId]/logs/utils.ts	Replaces hand-rolled relative-time ladder with formatRelativeTime; intentional visible changes: 'yesterday' → '1d ago', dates ≥7 days change from absolute 'Jan 5' to relative 'Xw/Xmo/Xy ago'
packages/logger/src/index.ts	Replaces inline Object.entries filter with filterUndefined; adds @sim/utils as a new dependency — zero-circularity confirmed
packages/workflow-persistence/src/subblocks.ts	Replaces combined null+undefined filter with filterUndefined + separate null-check; semantically equivalent at runtime
apps/sim/providers/utils.ts	Replaces forEach delete with omit(result, sourceIds); result is typed Record<string, any> so string[] keys are valid
apps/sim/lib/table/sql.ts	Replaces inline typeof/null/Array.isArray guard with isRecordLike; adds explicit as JsonValue cast in else branch
.github/workflows/test-build.yml	Wires bun run check:utils enforcement script into CI — previously unused in CI

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["apps/sim (93 files)"] --> B["@sim/utils"]
    C["packages/logger"] --> B
    D["packages/workflow-persistence"] --> B
    B --> E["errors\ngetErrorMessage / toError / getPostgresErrorCode"]
    B --> F["string\nnormalizeEmail / truncate"]
    B --> G["retry\nbackoffWithJitter / parseRetryAfter"]
    B --> H["formatting\nformatDate / formatDateTime\nformatRelativeTime / getTimezoneAbbreviation"]
    B --> I["object\nfilterUndefined / omit / isRecordLike"]
    B --> J["helpers\nsleep / noop"]
    K[".github/workflows/test-build.yml"] --> L["bun run check:utils\n(CI enforcement)"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A["apps/sim (93 files)"] --> B["@sim/utils"]
    C["packages/logger"] --> B
    D["packages/workflow-persistence"] --> B
    B --> E["errors\ngetErrorMessage / toError / getPostgresErrorCode"]
    B --> F["string\nnormalizeEmail / truncate"]
    B --> G["retry\nbackoffWithJitter / parseRetryAfter"]
    B --> H["formatting\nformatDate / formatDateTime\nformatRelativeTime / getTimezoneAbbreviation"]
    B --> I["object\nfilterUndefined / omit / isRecordLike"]
    B --> J["helpers\nsleep / noop"]
    K[".github/workflows/test-build.yml"] --> L["bun run check:utils\n(CI enforcement)"]

Loading

Comments Outside Diff (1)

1. apps/sim/lib/workflows/schedules/utils.ts, line 503 (link)

   getTimezoneAbbreviation falls back to raw IANA names for unlisted zones

   The shared getTimezoneAbbreviation from @sim/utils/formatting only covers 9 hardcoded IANA timezones, returning the raw timezone string (e.g. "Europe/Berlin") for everything else. The deleted local function used Intl.DateTimeFormat with timeZoneName: 'short' to resolve a proper abbreviation (e.g. "CET" or "CEST") for any valid IANA timezone. Users with timezones outside those 9 — Europe/Berlin, America/Toronto, Asia/Hong_Kong, Pacific/Auckland, etc. — will now see the full IANA string inside the parenthetical: "Every day at 9:00 AM (Europe/Berlin)" instead of "Every day at 9:00 AM (CET)".

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

_{Reviews (1): Last reviewed commit: "refactor(utils): consolidate duplicated ..." | Re-trigger Greptile}

[waleedlatif1]

Addressed both review findings on this branch:

• Cursor (tools/index.ts Retry-After cap): fixed in 1b4c9b8fe — parseRetryAfter now takes an optional maxMs so the skip-vs-retry comparison against retryConfig.maxDelayMs uses the raw uncapped value. Regression test added.
• Greptile (schedules/utils.ts timezone abbreviation regression): fixed in ef55cdaf6 — getTimezoneAbbreviation in @sim/utils/formatting now falls back to Intl.DateTimeFormat's generic short timeZoneName resolution for any valid IANA zone outside the 9 hardcoded entries, restoring the deleted local implementation's behavior. Regression test added.

Also fixed an unrelated CI test failure in app/api/schedules/execute/route.test.ts (c440d1ac9) — the test spied on Math.random(), which no longer has any effect now that the route uses randomInt() from @sim/utils/random (backed by crypto.getRandomValues()); switched the test to mock @sim/utils/random directly.