:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { DateTime } from 'luxon'
import { personProfileIgnoredPropertiesCounter, personProfileUpdateOutcomeCounter } from '~/common/persons/metrics'
import { FILTERED_PERSON_UPDATE_PROPERTIES } from '~/common/persons/person-property-utils'
import { PluginEvent } from '~/plugin-scaffold'
import { Properties } from '~/plugin-scaffold'
import { InternalPerson } from '~/types'
import {
EventOps,
applyEventPropertyUpdates,
computeOpsScalarUpdates,
extractEventOps,
foldOps,
refineEventOps,
} from './person-update'
// The scenarios below exercise the extract → refine pair end to end, the
// same composition the Postgres store runs per event.
const computeEventPropertyUpdates = (event: PluginEvent, personProperties: Properties, updateAllProperties = false) =>
refineEventOps(extractEventOps(event, updateAllProperties), personProperties, updateAllProperties)
jest.mock('~/common/persons/metrics', () => ({
personProfileUpdateOutcomeCounter: {
labels: jest.fn().mockReturnValue({
inc: jest.fn(),
}),
},
personProfileIgnoredPropertiesCounter: {
labels: jest.fn().mockReturnValue({
inc: jest.fn(),
}),
},
}))
const mockPersonProfileUpdateOutcomeCounter = personProfileUpdateOutcomeCounter as jest.Mocked<
typeof personProfileUpdateOutcomeCounter
>
const mockPersonProfileIgnoredPropertiesCounter = personProfileIgnoredPropertiesCounter as jest.Mocked<
typeof personProfileIgnoredPropertiesCounter
>
describe('person-update', () => {
beforeEach(() => {
jest.clearAllMocks()
})
describe('computeEventPropertyUpdates', () => {
describe('property changes', () => {
it('should compute updates when custom properties are updated', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { custom_prop: 'new_value' },
},
} as any
const personProperties = { custom_prop: 'old_value' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ custom_prop: 'new_value' })
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
expect(mockPersonProfileUpdateOutcomeCounter.labels({ outcome: 'changed' }).inc).toHaveBeenCalled()
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should compute updates when properties are unset', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$unset: ['prop_to_remove'],
},
} as any
const personProperties = { prop_to_remove: 'value', other_prop: 'keep' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toUnset).toEqual(['prop_to_remove'])
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
it('should compute updates when setting a new property', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { new_prop: 'value' },
},
} as any
const personProperties = {}
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ new_prop: 'value' })
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
it('should compute updates when $set_once sets a property that does not exist', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set_once: { first_seen: '2024-01-01' },
},
} as any
const personProperties = {}
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ first_seen: '2024-01-01' })
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
it('should compute updates when a new eventToPersonProperty is set (not just updated)', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $browser: 'Chrome' },
},
} as any
const personProperties = {}
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $browser: 'Chrome' })
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
})
describe('filtered properties behavior', () => {
it.each(Array.from(FILTERED_PERSON_UPDATE_PROPERTIES))(
'should mark "%s" as ignored when updated',
(propertyName) => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { [propertyName]: 'new_value' },
},
} as any
const personProperties = { [propertyName]: 'old_value' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ [propertyName]: 'new_value' })
expect(result.shouldForceUpdate).toBe(false)
// Filtered properties are marked as ignored
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'ignored' })
expect(mockPersonProfileUpdateOutcomeCounter.labels({ outcome: 'ignored' }).inc).toHaveBeenCalled()
expect(mockPersonProfileIgnoredPropertiesCounter.labels).toHaveBeenCalledWith({
property: propertyName,
})
expect(
mockPersonProfileIgnoredPropertiesCounter.labels({ property: propertyName }).inc
).toHaveBeenCalled()
}
)
it('surfaces the filtered-only verdict for store-side suppression', () => {
const filteredOnly = computeEventPropertyUpdates(
{ event: 'pageview', properties: { $set: { $browser: 'Chrome' } } } as any,
{ $browser: 'Firefox' }
)
expect(filteredOnly.hasChanges).toBe(true)
expect(filteredOnly.hasNonFilteredChanges).toBe(false)
const newKey = computeEventPropertyUpdates(
{ event: 'pageview', properties: { $set: { $browser: 'Chrome' } } } as any,
{}
)
expect(newKey.hasNonFilteredChanges).toBe(true)
})
it('should accept blocked $geoip_* property updates at event level (filtering happens at batch level)', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $geoip_latitude: 37.7749 },
},
} as any
const personProperties = { $geoip_latitude: 40.7128 }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $geoip_latitude: 37.7749 })
expect(result.shouldForceUpdate).toBe(false)
// At event level, blocked geoip properties would be marked as ignored
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'ignored' })
expect(mockPersonProfileIgnoredPropertiesCounter.labels).toHaveBeenCalledWith({
property: '$geoip_latitude',
})
})
it('should trigger update when $geoip_country_name changes (allowed geoip property)', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $geoip_country_name: 'United States' },
},
} as any
const personProperties = { $geoip_country_name: 'Canada' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $geoip_country_name: 'United States' })
expect(result.shouldForceUpdate).toBe(false)
// $geoip_country_name is allowed so should be marked as changed
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should trigger update when $geoip_city_name changes (allowed geoip property)', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $geoip_city_name: 'San Francisco' },
},
} as any
const personProperties = { $geoip_city_name: 'New York' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $geoip_city_name: 'San Francisco' })
expect(result.shouldForceUpdate).toBe(false)
// $geoip_city_name is allowed so should be marked as changed
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should update all geoip properties when allowed property ($geoip_country_name) changes alongside blocked ones', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: {
$geoip_country_name: 'United States',
$geoip_latitude: 37.7749,
$geoip_longitude: -122.4194,
$geoip_postal_code: '94102',
},
},
} as any
const personProperties = {
$geoip_country_name: 'Canada',
$geoip_latitude: 43.6532,
$geoip_longitude: -79.3832,
$geoip_postal_code: 'M5V',
}
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({
$geoip_country_name: 'United States',
$geoip_latitude: 37.7749,
$geoip_longitude: -122.4194,
$geoip_postal_code: '94102',
})
expect(result.shouldForceUpdate).toBe(false)
// Since $geoip_country_name is allowed, the update is marked as changed (not ignored)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
it('should accept filtered properties even when mixed with unchanged custom properties', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $current_url: 'https://example.com/new', custom_prop: 'same_value' },
},
} as any
const personProperties = { $current_url: 'https://example.com/old', custom_prop: 'same_value' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $current_url: 'https://example.com/new' })
expect(result.shouldForceUpdate).toBe(false)
// $current_url is filtered, so it should be marked as ignored
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'ignored' })
expect(mockPersonProfileIgnoredPropertiesCounter.labels).toHaveBeenCalledWith({
property: '$current_url',
})
})
it('should accept multiple filtered properties at event level', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: {
$current_url: 'https://example.com/new',
$pathname: '/new-path',
},
},
} as any
const personProperties = {
$current_url: 'https://example.com/old',
$pathname: '/old-path',
}
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.shouldForceUpdate).toBe(false)
// Filtered properties should be marked as ignored
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'ignored' })
expect(mockPersonProfileIgnoredPropertiesCounter.labels).toHaveBeenCalledWith({
property: '$current_url',
})
expect(mockPersonProfileIgnoredPropertiesCounter.labels).toHaveBeenCalledWith({ property: '$pathname' })
})
})
describe('no changes', () => {
it('should return no changes when no properties are provided', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {},
} as any
const personProperties = { existing_prop: 'value' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(false)
expect(result.toSet).toEqual({})
expect(result.toUnset).toEqual([])
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'no_change' })
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should return no changes when all properties have the same value', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { custom_prop: 'same_value' },
},
} as any
const personProperties = { custom_prop: 'same_value' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(false)
expect(result.toSet).toEqual({})
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'no_change' })
})
it('should return no changes when $set_once property already exists', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set_once: { first_seen: '2024-01-01' },
},
} as any
const personProperties = { first_seen: '2023-01-01' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(false)
expect(result.toSet).toEqual({})
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'no_change' })
})
it('should return no changes when trying to unset non-existent property', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$unset: ['non_existent_prop'],
},
} as any
const personProperties = { other_prop: 'value' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(false)
expect(result.toUnset).toEqual([])
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'no_change' })
})
})
describe('person events behavior', () => {
it('should compute updates for any property on $identify events', () => {
const event: PluginEvent = {
event: '$identify',
properties: {
$set: { $browser: 'Chrome' },
},
} as any
const personProperties = { $browser: 'Firefox' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $browser: 'Chrome' })
expect(result.shouldForceUpdate).toBe(true)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
it('should compute updates for any property on $set events', () => {
const event: PluginEvent = {
event: '$set',
properties: {
$set: { utm_source: 'google' },
},
} as any
const personProperties = { utm_source: 'twitter' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.shouldForceUpdate).toBe(true)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
it('should set shouldForceUpdate to false for non-person events', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $browser: 'Chrome' },
},
} as any
const personProperties = { $browser: 'Firefox' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.shouldForceUpdate).toBe(false)
})
})
describe('NO_PERSON_UPDATE_EVENTS behavior', () => {
it('should skip updates for $exception events regardless of properties', () => {
const event: PluginEvent = {
event: '$exception',
properties: {
$set: { custom_prop: 'new_value' },
},
} as any
const personProperties = { custom_prop: 'old_value' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(false)
expect(result.toSet).toEqual({})
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'unsupported' })
})
it('should skip updates for $$heatmap events regardless of properties', () => {
const event: PluginEvent = {
event: '$$heatmap',
properties: {
$set: { custom_prop: 'new_value' },
},
} as any
const personProperties = {}
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(false)
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'unsupported' })
})
})
describe('mixed scenarios', () => {
it('should compute updates when both custom and allowed properties change', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { custom_prop: 'new_value', $browser: 'Chrome' },
},
} as any
const personProperties = { custom_prop: 'old_value', $browser: 'Firefox' }
const result = computeEventPropertyUpdates(event, personProperties)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ custom_prop: 'new_value', $browser: 'Chrome' })
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'changed' })
})
})
describe('updateAllProperties flag enabled', () => {
it.each(Array.from(FILTERED_PERSON_UPDATE_PROPERTIES))(
'should trigger update for filtered property "%s" when updateAllProperties is true',
(propertyName) => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { [propertyName]: 'new_value' },
},
} as any
const personProperties = { [propertyName]: 'old_value' }
const result = computeEventPropertyUpdates(event, personProperties, true)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ [propertyName]: 'new_value' })
expect(result.shouldForceUpdate).toBe(true) // updateAllProperties forces updates
// With updateAllProperties=true, no metrics should be tracked
expect(mockPersonProfileUpdateOutcomeCounter.labels).not.toHaveBeenCalled()
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
}
)
it('should trigger update for $geoip_* properties when updateAllProperties is true', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $geoip_city_name: 'San Francisco' },
},
} as any
const personProperties = { $geoip_city_name: 'New York' }
const result = computeEventPropertyUpdates(event, personProperties, true)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $geoip_city_name: 'San Francisco' })
expect(result.shouldForceUpdate).toBe(true) // updateAllProperties forces updates
// With updateAllProperties=true, no metrics should be tracked
expect(mockPersonProfileUpdateOutcomeCounter.labels).not.toHaveBeenCalled()
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should trigger update for multiple allowed properties when updateAllProperties is true', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: {
$browser: 'Chrome',
$os: 'macOS',
},
},
} as any
const personProperties = {
$browser: 'Firefox',
$os: 'Windows',
}
const result = computeEventPropertyUpdates(event, personProperties, true)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $browser: 'Chrome', $os: 'macOS' })
expect(result.shouldForceUpdate).toBe(true) // updateAllProperties forces updates
// With updateAllProperties=true, no metrics should be tracked
expect(mockPersonProfileUpdateOutcomeCounter.labels).not.toHaveBeenCalled()
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should trigger update for mixed allowed and custom properties when updateAllProperties is true', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: { $browser: 'Chrome', custom_prop: 'same_value' },
},
} as any
const personProperties = { $browser: 'Firefox', custom_prop: 'same_value' }
const result = computeEventPropertyUpdates(event, personProperties, true)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({ $browser: 'Chrome' })
expect(result.shouldForceUpdate).toBe(true) // updateAllProperties forces updates
// With updateAllProperties=true, no metrics should be tracked
expect(mockPersonProfileUpdateOutcomeCounter.labels).not.toHaveBeenCalled()
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should trigger update for mixed $geoip_* and allowed properties when updateAllProperties is true', () => {
const event: PluginEvent = {
event: 'pageview',
properties: {
$set: {
$browser: 'Chrome',
$geoip_city_name: 'San Francisco',
$geoip_country_code: 'US',
},
},
} as any
const personProperties = {
$browser: 'Firefox',
$geoip_city_name: 'New York',
$geoip_country_code: 'CA',
}
const result = computeEventPropertyUpdates(event, personProperties, true)
expect(result.hasChanges).toBe(true)
expect(result.toSet).toEqual({
$browser: 'Chrome',
$geoip_city_name: 'San Francisco',
$geoip_country_code: 'US',
})
expect(result.shouldForceUpdate).toBe(true) // updateAllProperties forces updates
// With updateAllProperties=true, no metrics should be tracked
expect(mockPersonProfileUpdateOutcomeCounter.labels).not.toHaveBeenCalled()
expect(mockPersonProfileIgnoredPropertiesCounter.labels).not.toHaveBeenCalled()
})
it('should not change behavior for NO_PERSON_UPDATE_EVENTS when updateAllProperties is true', () => {
const event: PluginEvent = {
event: '$exception',
properties: {
$set: { $browser: 'Chrome' },
},
} as any
const personProperties = { $browser: 'Firefox' }
const result = computeEventPropertyUpdates(event, personProperties, true)
// NO_PERSON_UPDATE_EVENTS should still be skipped regardless of flag
expect(result.hasChanges).toBe(false)
expect(result.toSet).toEqual({})
expect(result.shouldForceUpdate).toBe(false)
expect(mockPersonProfileUpdateOutcomeCounter.labels).toHaveBeenCalledWith({ outcome: 'unsupported' })
})
})
})
describe('applyEventPropertyUpdates', () => {
it('should apply property updates and return updated person', () => {
const propertyUpdates = {
hasChanges: true,
toSet: { name: 'John', email: '[email protected]' },
toUnset: ['old_prop'],
shouldForceUpdate: false,
hasNonFilteredChanges: true,
}
const person = {
id: '1',
team_id: 123,
uuid: 'test-uuid',
properties: { old_prop: 'value', name: 'Jane' },
created_at: new Date(),
version: 0,
is_identified: false,
}
const [updatedPerson, wasUpdated] = applyEventPropertyUpdates(propertyUpdates, person as any)
expect(wasUpdated).toBe(true)
expect(updatedPerson.properties).toEqual({ name: 'John', email: '[email protected]' })
expect(updatedPerson.properties.old_prop).toBeUndefined()
})
it('should not modify original person object', () => {
const propertyUpdates = {
hasChanges: true,
toSet: { name: 'John' },
toUnset: [],
shouldForceUpdate: false,
hasNonFilteredChanges: true,
}
const person = {
id: '1',
team_id: 123,
uuid: 'test-uuid',
properties: { name: 'Jane' },
created_at: new Date(),
version: 0,
is_identified: false,
}
const [updatedPerson, _] = applyEventPropertyUpdates(propertyUpdates, person as any)
expect(person.properties.name).toBe('Jane')
expect(updatedPerson.properties.name).toBe('John')
expect(person).not.toBe(updatedPerson)
})
it('should return false for wasUpdated when no actual changes occur', () => {
const propertyUpdates = {
hasChanges: false,
toSet: { name: 'John' },
toUnset: [],
shouldForceUpdate: false,
hasNonFilteredChanges: false,
}
const person = {
id: '1',
team_id: 123,
uuid: 'test-uuid',
properties: { name: 'John' },
created_at: new Date(),
version: 0,
is_identified: false,
}
const [_, wasUpdated] = applyEventPropertyUpdates(propertyUpdates, person as any)
expect(wasUpdated).toBe(false)
})
})
describe('computeOpsScalarUpdates', () => {
const personState = (overrides: Partial<InternalPerson>): InternalPerson =>
({ properties: {}, is_identified: false, last_seen_at: null, ...overrides }) as unknown as InternalPerson
const ops = (overrides: Partial<EventOps>): EventOps => ({
set: {},
setOnce: {},
unset: [],
denied: false,
shouldForceUpdate: false,
eventName: '$set',
...overrides,
})
it.each([
['identifies an unidentified person', { isIdentified: true }, {}, { is_identified: true }],
['does not re-identify an identified person', { isIdentified: true }, { is_identified: true }, {}],
['never reverts identification', {}, { is_identified: true }, {}],
] as [string, Partial<EventOps>, Partial<InternalPerson>, Partial<InternalPerson>][])(
'%s',
(_label, opOverrides, personOverrides, expected) => {
expect(computeOpsScalarUpdates(ops(opOverrides), personState(personOverrides))).toEqual(expected)
}
)
it('advances last_seen_at only forward', () => {
const older = DateTime.fromMillis(3_600_000, { zone: 'utc' })
const newer = DateTime.fromMillis(7_200_000, { zone: 'utc' })
const seenAt = personState({ last_seen_at: older } as unknown as Partial<InternalPerson>)
expect(computeOpsScalarUpdates(ops({ lastSeenAtMs: 7_200_000 }), seenAt)).toEqual({
last_seen_at: newer,
})
const current = personState({ last_seen_at: newer } as unknown as Partial<InternalPerson>)
expect(computeOpsScalarUpdates(ops({ lastSeenAtMs: 3_600_000 }), current)).toEqual({})
})
it('denied ops still contribute their scalars', () => {
// The denylist gates property writes only; both stores and
// the leader advance identity and last-seen regardless.
const updates = computeOpsScalarUpdates(
ops({ denied: true, isIdentified: true, lastSeenAtMs: 3_600_000 }),
personState({})
)
expect(updates.is_identified).toBe(true)
expect(updates.last_seen_at?.toMillis()).toBe(3_600_000)
})
})
describe('fold equivalence', () => {
// Deterministic PRNG (mulberry32): the sweep must reproduce
// identically on every run.
const mulberry32 = (seed: number) => (): number => {
seed = (seed + 0x6d2b79f5) | 0
let t = Math.imul(seed ^ (seed >>> 15), 1 | seed)
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
return ((t ^ (t >>> 14)) >>> 0) / 4294967296
}
const KEYS = ['k1', 'k2', 'k3']
const randomProps = (rand: () => number): Record<string, string> =>
Object.fromEntries(KEYS.filter(() => rand() < 0.4).map((k) => [k, `v${Math.floor(rand() * 4)}`]))
const randomOps = (rand: () => number): EventOps => {
const set = randomProps(rand)
const setOnce = Object.fromEntries(Object.entries(randomProps(rand)).filter(([k]) => !(k in set)))
return {
set,
// extractEventOps guarantees an event's set_once keys are
// not among its set keys; the generator upholds the same
// invariant so the sweep covers reachable shapes only.
setOnce,
unset: KEYS.filter(() => rand() < 0.25),
denied: false,
shouldForceUpdate: false,
isIdentified: rand() < 0.2 ? true : undefined,
lastSeenAtMs: rand() < 0.3 ? 3_600_000 * (1 + Math.floor(rand() * 3)) : undefined,
eventName: '$set',
}
}
const personWith = (properties: Record<string, string>): InternalPerson =>
({ properties, is_identified: false }) as unknown as InternalPerson
// This is the algebra the personhog store stakes its correctness
// on: folding a person's ops across a batch and refining the
// fold once must land on the same state as refining each event
// sequentially against evolving state, for every interleaving of
// set, set_once, and unset over shared keys.
it('folding into segments then refining each matches refining every op sequentially', () => {
const rand = mulberry32(20260807)
let segmentedRounds = 0
for (let round = 0; round < 500; round++) {
const baseProps = randomProps(rand)
const opsList = Array.from({ length: 2 + Math.floor(rand() * 4) }, () => randomOps(rand))
let sequential = personWith({ ...baseProps })
let seqIdentified = false
let seqLastSeen: number | null = null
for (const o of opsList) {
const refined = refineEventOps(o, sequential.properties, false)
;[sequential] = applyEventPropertyUpdates(refined, sequential)
seqIdentified = seqIdentified || o.isIdentified === true
if (o.lastSeenAtMs !== undefined) {
seqLastSeen = Math.max(seqLastSeen ?? 0, o.lastSeenAtMs)
}
}
// Exactly the store's lane discipline: fold onto the last
// segment, cut a new one when the composition is not
// representable, write segments in order.
const segments: EventOps[] = [opsList[0]]
for (const o of opsList.slice(1)) {
const folded = foldOps(segments[segments.length - 1], o)
if (folded === null) {
segments.push(o)
} else {
segments[segments.length - 1] = folded
}
}
if (segments.length > 1) {
segmentedRounds++
}
let candidate = personWith({ ...baseProps })
let candIdentified = false
let candLastSeen: number | null = null
for (const seg of segments) {
const refined = refineEventOps(seg, candidate.properties, false)
;[candidate] = applyEventPropertyUpdates(refined, candidate)
candIdentified = candIdentified || seg.isIdentified === true
if (seg.lastSeenAtMs !== undefined) {
candLastSeen = Math.max(candLastSeen ?? 0, seg.lastSeenAtMs)
}
}
const context = { round, baseProps, opsList }
expect({ ...context, out: candidate.properties }).toEqual({
...context,
out: sequential.properties,
})
expect(candIdentified).toBe(seqIdentified)
expect(candLastSeen).toBe(seqLastSeen)
}
// The sweep must actually exercise the segmentation path, or
// the null branch is dead weight it never validates.
expect(segmentedRounds).toBeGreaterThan(0)
})
})
describe('foldOps', () => {
const eventOps = (properties: Record<string, unknown>, event = '$set') =>
extractEventOps({ event, properties } as any)
const fold = (existing: EventOps, incoming: EventOps): EventOps => {
const folded = foldOps(existing, incoming)
expect(folded).not.toBeNull()
return folded!
}
it('preserves sequential semantics per key across folded events', () => {
// set shadows a pending set_once; among set_onces the first
// wins; an unset clears both lanes; a set_once after an unset
// becomes an unconditional set.
let acc = eventOps({ $set_once: { plan: 'first', keep: 'kept' } })
acc = fold(acc, eventOps({ $set: { plan: 'shadowing' }, $set_once: { keep: 'second-loses' } }))
acc = fold(acc, eventOps({ $unset: ['gone', 'revived'] }))
acc = fold(acc, eventOps({ $set_once: { revived: 'promoted' } }))
expect(acc.set).toEqual({ plan: 'shadowing', revived: 'promoted' })
expect(acc.setOnce).toEqual({ keep: 'kept' })
expect(acc.unset).toEqual(['gone'])
})
it('a later set supersedes a pending unset for its key', () => {
const acc = fold(eventOps({ $unset: ['a'] }), eventOps({ $set: { a: 'back' } }))
expect(acc.set).toEqual({ a: 'back' })
expect(acc.unset).toEqual([])
})
it('a same-event value and unset pair rides the fold whole', () => {
// The pair's outcome is snapshot-dependent (present resolves
// to gone, absent to the value), so both lanes must survive
// for refinement to decide — dropping either loses one branch.
const acc = fold(eventOps({ $set: { other: 'x' } }), eventOps({ $set_once: { k: 'v' }, $unset: ['k'] }))
expect(acc.setOnce).toEqual({ k: 'v' })
expect(acc.unset).toEqual(['k'])
})
it('a pair over pending value state resolves to a plain unset', () => {
// Pending state guarantees the key present at refinement, so
// the pair's present branch (gone) is the only reachable one.
const acc = fold(eventOps({ $set: { k: 'pending' } }), eventOps({ $set_once: { k: 'v' }, $unset: ['k'] }))
expect(acc.set).toEqual({})
expect(acc.setOnce).toEqual({})
expect(acc.unset).toEqual(['k'])
})
it.each([
['a set_once', { $set_once: { k: 'later' } }],
['another pair', { $set_once: { k: 'later' }, $unset: ['k'] }],
])('%s over a pending pair cuts a segment', (_label, later) => {
// "Present resolves one way, absent another with a different
// value" has no lane representation; the caller must write the
// accumulated ops and fold onward from the incoming event.
const pair = eventOps({ $set_once: { k: 'v' }, $unset: ['k'] })
expect(foldOps(pair, eventOps(later))).toBeNull()
})
it('identity ORs and last-seen max-merges, mirroring the leader', () => {
const first = eventOps({})
first.isIdentified = true
first.lastSeenAtMs = 7_200_000
const second = eventOps({})
second.lastSeenAtMs = 3_600_000
const acc = fold(first, second)
expect(acc.isIdentified).toBe(true)
expect(acc.lastSeenAtMs).toEqual(7_200_000)
})
it('denied events contribute nothing in either direction', () => {
const denied = eventOps({ $set: { a: '1' } }, '$exception')
const real = eventOps({ $set: { b: '2' } })
expect(foldOps(real, denied)).toEqual(real)
expect(foldOps(denied, real)).toEqual(real)
})
describe('exhaustive single-key transition table', () => {
const K = 'k'
type Shape = Record<string, unknown> | null
// Every reachable accumulated state, named by the ops that
// produce it, and every per-key shape one event can carry.
const STATES: [string, Shape][] = [
['empty', null],
['pending set', { $set: { [K]: 'p-set' } }],
['pending set_once', { $set_once: { [K]: 'p-once' } }],
['pending unset', { $unset: [K] }],
['pending set pair', { $set: { [K]: 'p-pair' }, $unset: [K] }],
['pending set_once pair', { $set_once: { [K]: 'p-pair' }, $unset: [K] }],
]
const INCOMING: [string, Record<string, unknown>][] = [
['set', { $set: { [K]: 'i-set' } }],
['set_once', { $set_once: { [K]: 'i-once' } }],
['unset', { $unset: [K] }],
['set pair', { $set: { [K]: 'i-pair' }, $unset: [K] }],
['set_once pair', { $set_once: { [K]: 'i-pair' }, $unset: [K] }],
]
// The pair state is the one place composition can lose
// information, and only under an incoming op that is itself
// snapshot-dependent for the key.
const SEGMENTS = new Set(
['pending set pair', 'pending set_once pair'].flatMap((s) =>
['set_once', 'set pair', 'set_once pair'].map((i) => `${s}|${i}`)
)
)
const CASES = STATES.flatMap(([stateLabel, stateProps]) =>
INCOMING.flatMap(([inLabel, inProps]) =>
[
['absent', {}],
['present', { [K]: 'existing' }],
].map(([snapLabel, snapshot]) => [stateLabel, inLabel, snapLabel, stateProps, inProps, snapshot])
)
) as [string, string, string, Shape, Record<string, unknown>, Properties][]
const applySequentially = (events: Record<string, unknown>[], snapshot: Properties): Properties => {
let personState = { properties: { ...snapshot }, is_identified: false } as unknown as InternalPerson
for (const properties of events) {
const refined = refineEventOps(eventOps(properties), personState.properties, false)
;[personState] = applyEventPropertyUpdates(refined, personState)
}
return personState.properties
}
it.each(CASES)(
'%s then %s over %s key: fold matches sequential refinement',
(stateLabel, inLabel, _snapLabel, stateProps, inProps, snapshot) => {
const events = stateProps === null ? [inProps] : [stateProps, inProps]
const sequential = applySequentially(events, snapshot)
const accumulated = eventOps(stateProps ?? {})
const folded = foldOps(accumulated, eventOps(inProps))
if (folded === null) {
expect(SEGMENTS.has(`${stateLabel}|${inLabel}`)).toBe(true)
// A cut segment writes each side as its own leader
// call, which is the sequential application above
// by construction — nothing further to assert.
return
}
expect(SEGMENTS.has(`${stateLabel}|${inLabel}`)).toBe(false)
let personState = { properties: { ...snapshot }, is_identified: false } as unknown as InternalPerson
const refined = refineEventOps(folded, personState.properties, false)
;[personState] = applyEventPropertyUpdates(refined, personState)
expect(personState.properties).toEqual(sequential)
}
)
})
it('a denied event still contributes its identity and last-seen scalars', () => {
// The denylist gates property writes only; both stores and
// the leader advance the scalars regardless of event kind.
const denied = eventOps({ $set: { a: '1' } }, '$exception')
denied.lastSeenAtMs = 7_200_000
denied.isIdentified = true
const real = eventOps({ $set: { b: '2' } })
const acc = fold(real, denied)
expect(acc.set).toEqual(real.set)
expect(acc.isIdentified).toBe(true)
expect(acc.lastSeenAtMs).toBe(7_200_000)
})
})
})