@synchronized-console/shared 2.25.7 → 2.31.14

package/src/core/helpers/error.spec.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect } from 'vitest'
+import { errorToString, getErrorMessage } from './error.js'
+
+describe('errorToString', () => {
+  it('should stringify non-Error objects', () => {
+    const obj = { foo: 'bar', num: 42 }
+    const result = errorToString(obj)
+    expect(result).toBe('{"foo":"bar","num":42}')
+  })
+
+  it('should handle primitive values', () => {
+    expect(errorToString('string error')).toBe('"string error"')
+    expect(errorToString(123)).toBe('123')
+    expect(errorToString(true)).toBe('true')
+    expect(errorToString(null)).toBe('null')
+    expect(errorToString(undefined)).toBeUndefined()
+  })
+
+  it('should fallback to String() for non-serializable objects', () => {
+    const circular: Record<string, unknown> = { name: 'circular' }
+    circular.self = circular
+
+    const result = errorToString(circular)
+    expect(result).toBe('[object Object]')
+  })
+
+  it('should return stack trace for Error objects', () => {
+    const error = new Error('Test error')
+    const result = errorToString(error)
+
+    expect(result).toContain('Test error')
+    expect(result).toContain('Error: Test error')
+  })
+
+  it('should fallback to message if no stack', () => {
+    const error = new Error('Test message')
+    // Remove stack to test fallback
+    delete (error as Error & { stack?: string }).stack
+
+    const result = errorToString(error)
+    expect(result).toBe('Test message')
+  })
+
+  it('should fallback to String(error) if no stack or message', () => {
+    const error = new Error()
+    delete (error as Error & { stack?: string }).stack
+    // Use Reflect.deleteProperty to avoid TypeScript error
+    Reflect.deleteProperty(error, 'message')
+
+    const result = errorToString(error)
+    expect(result).toBe('Error')
+  })
+
+  it('should handle Error with cause property', () => {
+    const rootCause = new Error('Root cause')
+    const error = new Error('Main error') as Error & { cause?: Error }
+    error.cause = rootCause
+
+    const result = errorToString(error)
+    expect(result).toContain('Main error')
+    expect(result).toContain('Cause: ')
+    expect(result).toContain('Root cause')
+  })
+
+  it('should handle Error with jse_cause property', () => {
+    const rootCause = new Error('JSE root cause')
+    const error = new Error('Main error') as Error & { jse_cause?: Error }
+    error['jse_cause'] = rootCause
+
+    const result = errorToString(error)
+    expect(result).toContain('Main error')
+    expect(result).toContain('Cause: ')
+    expect(result).toContain('JSE root cause')
+  })
+
+  it('should handle nested causes recursively', () => {
+    const deepCause = new Error('Deep cause')
+    const midCause = new Error('Mid cause') as Error & { cause?: Error }
+    midCause.cause = deepCause
+
+    const error = new Error('Top error') as Error & { cause?: Error }
+    error.cause = midCause
+
+    const result = errorToString(error)
+    expect(result).toContain('Top error')
+    expect(result).toContain('Mid cause')
+    expect(result).toContain('Deep cause')
+
+    // Should have nested "Cause:" labels
+    const causeCount = (result.match(/Cause: /g) || []).length
+    expect(causeCount).toBe(2)
+  })
+
+  it('should prioritize jse_cause over cause when both are present', () => {
+    const jseCause = new Error('JSE cause')
+    const stdCause = new Error('Standard cause')
+
+    const error = new Error('Main error') as Error & {
+      cause?: Error
+      jse_cause?: Error
+    }
+    error.cause = stdCause
+    error['jse_cause'] = jseCause
+
+    const result = errorToString(error)
+    expect(result).toContain('Main error')
+    expect(result).toContain('JSE cause')
+    // Should NOT contain cause since jse_cause takes priority
+    expect(result).not.toContain('Standard cause')
+
+    // Should have only one "Cause:" label
+    const causeCount = (result.match(/Cause: /g) || []).length
+    expect(causeCount).toBe(1)
+  })
+
+  it('should handle cause when jse_cause is not present', () => {
+    const stdCause = new Error('Standard cause')
+
+    const error = new Error('Main error') as Error & { cause?: Error }
+    error.cause = stdCause
+
+    const result = errorToString(error)
+    expect(result).toContain('Main error')
+    expect(result).toContain('Standard cause')
+
+    // Should have one "Cause:" label
+    const causeCount = (result.match(/Cause: /g) || []).length
+    expect(causeCount).toBe(1)
+  })
+
+  it('should handle error with no cause properties', () => {
+    const error = new Error('Error without cause')
+
+    const result = errorToString(error)
+    expect(result).toContain('Error without cause')
+    expect(result).not.toContain('Cause:')
+
+    // Should have no "Cause:" labels
+    const causeCount = (result.match(/Cause: /g) || []).length
+    expect(causeCount).toBe(0)
+  })
+
+  it('should handle non-Error causes', () => {
+    const error = new Error('Main error') as Error & { cause?: unknown }
+    error.cause = { type: 'custom', message: 'Custom cause' }
+
+    const result = errorToString(error)
+    expect(result).toContain('Main error')
+    expect(result).toContain('Cause: {"type":"custom","message":"Custom cause"}')
+  })
+
+  it('should handle circular reference in causes', () => {
+    const error = new Error('Main error') as Error & { cause?: unknown }
+    const cause: Record<string, unknown> = { message: 'Circular cause' }
+    cause.self = cause
+    error.cause = cause
+
+    const result = errorToString(error)
+    expect(result).toContain('Main error')
+    expect(result).toContain('Cause: [object Object]')
+  })
+})
+
+describe('getErrorMessage', () => {
+  it('should return message from Error objects', () => {
+    const error = new Error('Test error message')
+    const result = getErrorMessage(error)
+    expect(result).toBe('Test error message')
+  })
+
+  it('should return message from objects with message property', () => {
+    const errorLike = { message: 'Custom error message', code: 500 }
+    const result = getErrorMessage(errorLike)
+    expect(result).toBe('Custom error message')
+  })
+
+  it('should return string values directly', () => {
+    const stringError = 'This is a string error'
+    const result = getErrorMessage(stringError)
+    expect(result).toBe('This is a string error')
+  })
+
+  it('should ignore non-string message properties', () => {
+    const errorLike = { message: 123, other: 'value' }
+    const result = getErrorMessage(errorLike)
+    expect(result).toBe('{"message":123,"other":"value"}')
+  })
+
+  it('should stringify objects without message property', () => {
+    const obj = { foo: 'bar', num: 42 }
+    const result = getErrorMessage(obj)
+    expect(result).toBe('{"foo":"bar","num":42}')
+  })
+
+  it('should handle primitive values', () => {
+    expect(getErrorMessage(123)).toBe('123')
+    expect(getErrorMessage(true)).toBe('true')
+    expect(getErrorMessage(null)).toBe('null')
+    expect(getErrorMessage(undefined)).toBe('undefined')
+  })
+
+  it('should fallback to String() for non-serializable objects', () => {
+    const circular: Record<string, unknown> = { name: 'circular' }
+    circular.self = circular
+
+    const result = getErrorMessage(circular)
+    expect(result).toBe('[object Object]')
+  })
+
+  it('should handle empty Error message', () => {
+    const error = new Error('')
+    const result = getErrorMessage(error)
+    expect(result).toBe('')
+  })
+})

package/src/core/helpers/error.ts

@@ -1,3 +1,5 @@
+import { get, isObject, isString, isUndefined } from '#lodash'
+
 class UnexpectedErrorStructureError extends Error {}
 
 /**
@@ -36,13 +38,68 @@ export function createUncoveredError(e: unknown) {
   return new UncoveredError(`Uncovered error case ${errorRepr}.`)
 }
 
+/**
+ * A custom error class that produces a cleaner stack trace when instantiated.
+ */
+export class CleanStackTrace extends Error {
+  constructor() {
+    super('')
+    this.name = 'Stack trace:'
+  }
+}
+
 /**
  * Note: Only V8 and Node.js support controlling the stack trace limit
  */
 export const collectLongTrace = (limit?: number) => {
   const originalLimit = Error.stackTraceLimit
   Error.stackTraceLimit = limit || 30
-  const trace = (new Error().stack || '').split('\n').slice(1).join('\n').trim()
+  const trace = (new CleanStackTrace().stack || '')
+    .split('\n')
+    .slice(2) // remove "Error" and this function's own frame
+    .join('\n')
+    .trim()
   Error.stackTraceLimit = originalLimit
   return trace
 }
+
+/**
+ * When you need to log a full error representation, w/ full .cause() support
+ */
+export const errorToString = (e: unknown): string => {
+  if (!(e instanceof Error)) {
+    try {
+      return JSON.stringify(e)
+    } catch {
+      return String(e)
+    }
+  }
+
+  let ret = e.stack || e.message || String(e)
+  const causeProps = ['jse_cause', 'cause'] as const
+
+  for (const prop of causeProps) {
+    if (prop in e) {
+      const cause = get(e, prop)
+      if (!cause) continue
+
+      ret += `\nCause: ${errorToString(cause)}`
+      break // avoid chaining multiple causes
+    }
+  }
+
+  return ret
+}
+
+export const getErrorMessage = (e: unknown): string => {
+  if (e instanceof Error) return e.message
+  if (isObject(e) && 'message' in e && isString(e.message)) return e.message
+  if (isString(e)) return e
+  if (isUndefined(e)) return 'undefined'
+
+  try {
+    return JSON.stringify(e)
+  } catch {
+    return String(e)
+  }
+}

package/src/core/helpers/url.ts

@@ -8,10 +8,16 @@ export class RelativeURL extends URL {
     super(url, RelativeURL.#fakeOrigin)
   }
 
+  /**
+   * @deprecated Not supported in relative URL
+   */
   get host(): string {
     throw new Error('host is not supported in a relative URL')
   }
 
+  /**
+   * @deprecated Not supported in relative URL
+   */
   get hostname(): string {
     throw new Error('hostname is not supported in a relative URL')
   }
@@ -20,26 +26,53 @@ export class RelativeURL extends URL {
     return this.pathname + this.search + this.hash
   }
 
+  /**
+   * @deprecated Not supported in relative URL
+   */
   get origin(): string {
     throw new Error('origin is not supported in a relative URL')
   }
 
+  /**
+   * @deprecated Not supported in relative URL
+   */
   get password(): string {
     throw new Error('password is not supported in a relative URL')
   }
 
+  /**
+   * @deprecated Not supported in relative URL
+   */
   get protocol(): string {
     throw new Error('protocol is not supported in a relative URL')
   }
 
+  /**
+   * @deprecated Not supported in relative URL
+   */
   get port(): string {
     throw new Error('port is not supported in a relative URL')
   }
 
+  /**
+   * @deprecated Not supported in relative URL
+   */
   get username(): string {
     throw new Error('username is not supported in a relative URL')
   }
 
+  get path(): string {
+    return this.pathname
+  }
+
+  get pathOnly(): string {
+    return this.pathname
+  }
+
+  get fullPath(): string {
+    return this.href
+  }
+
   toJSON(): string {
     return this.href
   }

package/src/core/helpers/utility.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import { xor } from './utility.js'
+import { xor, StringEnum } from './utility.js'
 
 describe('xor', () => {
   test('returns true if only one of the arguments is truthy', () => {
@@ -9,3 +9,21 @@ describe('xor', () => {
     expect(xor(false, false)).toBe(false)
   })
 })
+
+describe('StringEnum', () => {
+  const Colors = StringEnum(['RED', 'GREEN', 'BLUE'])
+
+  test('creates an object with keys and values matching the input strings', () => {
+    expect(Colors).toEqual({
+      RED: 'RED',
+      GREEN: 'GREEN',
+      BLUE: 'BLUE'
+    })
+  })
+
+  test('works with empty array', () => {
+    const EmptyEnum = StringEnum([])
+    expect(EmptyEnum).toEqual({})
+    expect(Object.isFrozen(EmptyEnum)).toBe(true)
+  })
+})

package/src/core/helpers/utility.ts

@@ -167,3 +167,34 @@ export const waitForever = (): Promise<never> => new Promise<never>(noop)
  * Returns true if only one of the arguments is truthy
  */
 export const xor = (a: unknown, b: unknown) => !!((a || b) && !(a && b))
+
+/**
+ * Shortcut for creating string key & value enums. Native TS Enums are problematic in many ways
+ * (transform code, instead of just adding types; you cant put a string literal matching the enum value
+ * in a variable typed as the enum, etc.)
+ */
+export const StringEnum = <T extends string>(args: T[]) => {
+  const enumObj = Object.fromEntries(args.map((arg) => [arg, arg])) as {
+    [K in T]: K
+  }
+  return Object.freeze(enumObj)
+}
+
+/**
+ * Shortcut for (typeof StringEnum)[keyof typeof StringEnum]
+ */
+export type StringEnumValues<T extends Record<string, string>> = {
+  [K in keyof T]: T[K] extends string ? T[K] : never
+}[keyof T]
+
+/**
+ * Get first non-undefined/null value, or undefined if none found
+ */
+export const firstDefinedValue = <T>(
+  ...args: (T | undefined | null)[]
+): T | undefined => {
+  for (const arg of args) {
+    if (!isNullOrUndefined(arg)) return arg
+  }
+  return undefined
+}

package/src/core/index.ts

@@ -7,7 +7,9 @@ export * from './helpers/utilityTypes.js'
 export * from './helpers/tracking.js'
 export * from './utils/localStorage.js'
 export * from './utils/md5.js'
+export * from './utils/base64.js'
 export * from './helpers/os.js'
 export * from './helpers/optimization.js'
 export * from './helpers/debugging.js'
 export * from './helpers/url.js'
+export * from './helpers/encoding.js'

package/src/core/utils/base64.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { base64Decode, base64Encode } from './base64.js'
+
+describe('base64Encode & base64Decode', () => {
+  it('should encode/decode a string to base64', () => {
+    const str = 'Hello, World!'
+    const encoded = base64Encode(str)
+    expect(encoded).toBe('SGVsbG8sIFdvcmxkIQ==')
+
+    const decoded = base64Decode(encoded)
+    expect(decoded).toBe(str)
+  })
+
+  it('should handle empty strings', () => {
+    const str = ''
+    const encoded = base64Encode(str)
+    expect(encoded).toBe('')
+
+    const decoded = base64Decode(encoded)
+    expect(decoded).toBe(str)
+  })
+
+  it('should handle special characters', () => {
+    const str = '¡Hola, Mundo!'
+    const encoded = base64Encode(str)
+    expect(encoded).toBe('wqFIb2xhLCBNdW5kbyE=')
+
+    const decoded = base64Decode(encoded)
+    expect(decoded).toBe(str)
+  })
+})

package/src/core/utils/base64.ts

@@ -0,0 +1,19 @@
+export function base64Encode(val: string): string {
+  if (typeof window === 'undefined') {
+    // Node.js
+    return Buffer.from(val, 'utf8').toString('base64')
+  } else {
+    // Browser
+    return btoa(unescape(encodeURIComponent(val)))
+  }
+}
+
+export function base64Decode(val: string): string {
+  if (typeof window === 'undefined') {
+    // Node.js
+    return Buffer.from(val, 'base64').toString('utf8')
+  } else {
+    // Browser
+    return decodeURIComponent(escape(atob(val)))
+  }
+}

package/src/environment/db.spec.ts

@@ -0,0 +1,48 @@
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { regionConfigSchema } from './db.js'
+
+describe('Database Configuration', () => {
+  let baseNodeEnv: string
+
+  beforeAll(() => {
+    baseNodeEnv = process.env.NODE_ENV || ''
+  })
+
+  afterEach(() => {
+    process.env.NODE_ENV = baseNodeEnv
+  })
+
+  it('regionConfigSchema does not allow skipInitialization in non-test environments', () => {
+    const validConfig = {
+      postgres: {
+        connectionUri: 'postgres://user:password@host:port/dbname',
+        databaseName: 'dbname',
+        privateConnectionUri: 'postgres://user:password@host:port/dbname',
+        publicTlsCertificate: 'cert',
+        skipInitialization: false
+      },
+      blobStorage: {
+        endpoint: 'https://s3.example.com',
+        publicEndpoint: 'https://public.s3.example.com',
+        accessKey: 'accessKey',
+        secretKey: 'secretKey',
+        bucket: 'bucketName',
+        createBucketIfNotExists: true,
+        s3Region: 'us-west-1'
+      }
+    }
+
+    process.env.NODE_ENV = 'test' // this should work
+    expect(() => regionConfigSchema.parse(validConfig)).not.toThrow()
+
+    const invalidConfig = {
+      ...validConfig,
+      postgres: { ...validConfig.postgres, skipInitialization: true }
+    }
+
+    process.env.NODE_ENV = 'production' // this should throw
+    expect(() => regionConfigSchema.parse(invalidConfig)).toThrow(
+      /skipInitialization can only be set when NODE_ENV is \\\"test\\\"/
+    )
+  })
+})

package/src/environment/{multiRegionConfig.ts → db.ts}

@@ -7,7 +7,7 @@ import { isUndefined, get } from '#lodash'
 // cause of knex's ESM/CJS interop issues
 const knex = get(Knex, 'knex') || get(Knex, 'default')
 
-const regionConfigSchema = z.object({
+export const regionConfigSchema = z.object({
   postgres: z.object({
     connectionUri: z
       .string()
@@ -29,10 +29,31 @@ const regionConfigSchema = z.object({
     publicTlsCertificate: z
       .string()
       .describe('Public TLS ("CA") certificate for the Postgres server')
+      .optional(),
+    skipInitialization: z
+      .boolean()
       .optional()
+      .describe(
+        'Skip database initialization (migration run & replication setup). Only used in tests.'
+      )
+      .refine((val) => val !== true || process.env.NODE_ENV === 'test', {
+        message: 'skipInitialization can only be set when NODE_ENV is "test"'
+      })
   }),
   blobStorage: z.object({
-    endpoint: z.string().url().describe('URL of the S3-compatible storage endpoint'),
+    endpoint: z
+      .string()
+      .url()
+      .describe(
+        'URL of the S3-compatible storage endpoint, accessible from the server'
+      ),
+    publicEndpoint: z
+      .string()
+      .url()
+      .optional()
+      .describe(
+        'Public URL of the S3-compatible storage endpoint, accessible from clients via the public internet'
+      ),
     accessKey: z.string().describe('Access key for the S3-compatible storage endpoint'),
     secretKey: z.string().describe('Secret key for the S3-compatible storage endpoint'),
     bucket: z.string().describe('Name of the S3-compatible storage bucket'),
@@ -89,8 +110,14 @@ export const loadMultiRegionsConfig = async ({
 
 export type KnexConfigArgs = {
   migrationDirs: string[]
-  isTestEnv: boolean
-  isDevOrTestEnv: boolean
+  /**
+   * Override migration source loader to load migrations a custom way
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  migrationSource?: any // no type from knex for this
+  isTestEnv?: boolean
+  isDevOrTestEnv?: boolean
+  isDevEnv?: boolean
   logger: Logger
   maxConnections: number
   applicationName: string
@@ -114,7 +141,8 @@ export const createKnexConfig = ({
   caCertificate,
   connectionAcquireTimeoutMillis,
   connectionCreateTimeoutMillis,
-  asyncStackTraces
+  asyncStackTraces,
+  migrationSource
 }: {
   connectionString?: string | undefined
   caCertificate?: string | undefined
@@ -127,8 +155,17 @@ export const createKnexConfig = ({
     client: 'pg',
     migrations: {
       extension: 'ts',
-      loadExtensions: isTestEnv ? ['.js', '.ts'] : ['.js'],
-      directory: migrationDirs
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      migrationSource,
+      // these warnings are annoying locally when switching branches:
+      disableMigrationsListValidation: !!isDevOrTestEnv,
+      ...(migrationSource
+        ? {}
+        : {
+            // Can only be set if migrationSource is not set
+            loadExtensions: isTestEnv ? ['.js', '.ts'] : ['.js'],
+            directory: migrationDirs
+          })
     },
     log: {
       warn(message: unknown) {
@@ -158,7 +195,7 @@ export const createKnexConfig = ({
       max: maxConnections,
       acquireTimeoutMillis: connectionAcquireTimeoutMillis, // If the maximum number of connections is reached, it wait for 16 seconds trying to acquire an existing connection before throwing a timeout error.
       createTimeoutMillis: connectionCreateTimeoutMillis // If no existing connection is available and the maximum number of connections is not yet reached, the pool will try to create a new connection for 5 seconds before throwing a timeout error.
-      // createRetryIntervalMillis: 200, // Irrelevant & ignored because propogateCreateError is true.
+      // createRetryIntervalMillis: 200, // Irrelevant & ignored because propagateCreateError is true.
       // propagateCreateError: true // The propagateCreateError is set to true by default in Knex and throws a TimeoutError if the first create connection to the database fails. Knex recommends that this value is NOT set to false, despite what 'helpful' people on Stackoverflow tell you: https://github.com/knex/knex/issues/3455#issuecomment-535554401
     }
   }
@@ -184,3 +221,20 @@ export const configureKnexClient = (
     : undefined
   return { public: knex(knexConfig), private: privateConfig }
 }
+
+export const getConnectionSettings = (
+  knex: Knex.Knex
+): {
+  connectionString?: string
+  ssl?: boolean
+  application_name?: string
+} => {
+  return (knex.client as Knex.Knex.Client).connectionSettings
+}
+
+export const obfuscateConnectionString = (connectionString: string): string => {
+  const url = new URL(connectionString)
+  const obfuscatedUrl = new URL(url)
+  obfuscatedUrl.password = '****'
+  return obfuscatedUrl.toString()
+}

package/src/environment/featureFlags.ts

@@ -0,0 +1,25 @@
+/**
+ * IMPORTANT: This should not have any node-only code (e.g. Zod)
+ */
+
+export type FeatureFlags = {
+  FF_AUTOMATE_MODULE_ENABLED: boolean
+  FF_GENDOAI_MODULE_ENABLED: boolean
+  FF_WORKSPACES_MODULE_ENABLED: boolean
+  FF_WORKSPACES_SSO_ENABLED: boolean
+  FF_GATEKEEPER_MODULE_ENABLED: boolean
+  FF_BILLING_INTEGRATION_ENABLED: boolean
+  FF_WORKSPACES_MULTI_REGION_ENABLED: boolean
+  FF_FORCE_ONBOARDING: boolean
+  FF_MOVE_PROJECT_REGION_ENABLED: boolean
+  FF_NO_PERSONAL_EMAILS_ENABLED: boolean
+  FF_RETRY_ERRORED_PREVIEWS_ENABLED: boolean
+  FF_PERSONAL_PROJECTS_LIMITS_ENABLED: boolean
+  FF_NEXT_GEN_FILE_IMPORTER_ENABLED: boolean
+  FF_RHINO_FILE_IMPORTER_ENABLED: boolean
+  FF_LEGACY_FILE_IMPORTS_ENABLED: boolean
+  FF_ACC_INTEGRATION_ENABLED: boolean
+  FF_DASHBOARDS_MODULE_ENABLED: boolean
+  FF_SAVED_VIEWS_ENABLED: boolean
+  FF_USERS_INVITE_SCOPE_IS_PUBLIC: boolean
+}