every (non-hidden) field of a snapshot rendered as an addition

apply a jsondiffpatch delta to a deep clone of the current state

Build the displayable change history for one entity from its raw audit docs.

A jsondiffpatch update-delta only encodes what changed (e.g. items added to an array by index), not the full prior value — so per-field before/after cannot be read from a single delta. Instead the full document state is replayed: starting from the create/baseline snapshot and applying each update delta in chronological order, the before/after of every field (including multi-value arrays) is the difference between consecutive full states.

events newest-first

chronological: by server timestamp, then by revision generation

The names of the fields one audit record changed, read directly from its raw diff, without replaying the entity's full document state.

This is what the system-wide change log needs: a top-level jsondiffpatch delta is already keyed by field name, so the names (unlike the before/after values, see buildChangeEvents) need no prior state. That makes a row renderable from its own audit doc alone, so the log can page over records of many different entities without loading a history per entity.

A delete returns no fields on purpose: a deletion replicates as a tombstone stripped of its content, so the delta would list every field of the record as removed rather than the one thing that happened.

the (non-hidden) fields whose full value differs between two states

the full document snapshot carried by a baseline (raw doc) or create ([doc]) record

Decorator (Annotation @DatabaseField()) to mark a property of an Entity that should be persisted in the database.

also see

Returns the schema map of this entity (not the superclass). Creates and assigns a new one if it doesn't exist yet.

Comparing two values for equality that might be different than just object equality

Group an array by the given property.

an array where the first entry is the value of this group and the second all entries that have this value.

Read the contents of a Blob into an ArrayBuffer. Use this for binary formats (e.g. xlsx) where reading as text would corrupt the payload.

This is a simple shorthand function to create factories for services. The use case is, when multiple services extend the same class and one of these services will be provided.

Combine Mango selectors so that a document has to match all of them, leaving out empty ones (and the $and itself if only one is left).

The two queries that together return an entity type's documents sorted by a property, in the order in which to page through them.

A Mango index only contains the documents that have every indexed field (and cannot be told to treat a missing one like null), so a query sorted through an index on the property skips all documents without a value for it. These are queried separately, through a partial index containing only them.

Selector matching all documents of one entity type.

Apply all config migrations to a plain JSON document. Returns the migrated document as a plain object (no Angular entity re-hydration). Used by the admin CLI; ConfigService wraps this and also applies defaultConfigs (addDefaultNoteDetailsConfig, addDefaultTodoViews) before calling this, so the migrations above can see those default-added view configs too.

If the user previously opted into online-only mode, override session_type early so that database instances are created with the correct type from the start.

This MUST run before Angular bootstraps, because DatabaseFactoryService reads environment.session_type the first time a database is lazily accessed (during Angular DI startup, before LoginComponent even exists). If we waited until LoginComponent ran, the wrong DB class would already have been instantiated.

The flow is:

1. User toggles checkbox on login page → LoginComponent writes localStorage and reloads the page
2. On reload, this function runs and applies the preference to environment
3. Angular DI starts → correct DB class (RemotePouchDatabase) is created

See also: LoginComponent.onOnlineOnlyChanged() and ONLINE_ONLY_KEY.

Force online-only mode when bootstrapping a public-form route, so the database factory creates a RemotePouchDatabase from the first lazy access rather than a SyncedPouchDatabase that would never be initialized.

Load basic config values from assets/keycloak.json into environment

Overwrite environment settings with the settings from the config.json if present. If no file is found, the environment settings are kept.

Load Push Notifications config for Firebase. Please add assets/firebase-config.json with your own Firebase config

Load Keycloak server URL from assets/keycloak.json into environment

Applies a contiguous shift-selection update over a row index range.

Detects whether the click originated from a checkbox input.

Detects whether the click target is inside an element marked as .clickable.

Determines whether row-click handling should be skipped for this interaction.

Adds or removes a single record from the selected records collection.

Computes the next selection state for a row mousedown, including shift-range behavior.

Applies sorting rules to columns: disables sorting for entity references, untyped columns, and arrays (unless the datatype provides custom sort logic).

Infers a stable default sort from visible sortable columns. Date-like columns default to descending order.

Resolve the source field for virtual DisplayAge columns.

These columns display an age from another field, e.g. age reads record.dateOfBirth.age, so datatype sorting cannot use the column value directly. The legacy age and age_<field> conventions remain supported for existing configs.

Update the given entity by applying the text entered by a user to the most likely appropriate entity field, inferred from the toString representation.

Updates a list of entities given an updated version of the entity. This updated version can either be a new entity (that should be inserted into the list), or an existing entity that should be updated or deleted. The given array will not be mutated but will be returned when the given new entity or type is illegal

An array of the given entities with the update applied

Convert wrap a value in an array if it is not already an array.

One filter option per record a login account can belong to.

Matched on every shape the author can be recorded in: the backend writes what the access token carried, which is the record's id where the account names one and the plain username otherwise. The username is the record id without its type prefix, which is how an account without an explicit id is linked to its record in the first place (see KeycloakAuthService).

One filter option per entity type, each selecting that type's records by a prefix range on the raw stored id.

It is legal in a selector even though AuditRecord declares no property of that name - see the class.

One filter option per operation the log lets the user narrow to.

A fresh copy of the design document to create in the audit database.

Built per call rather than shared: saveDatabaseIndex stamps aam_version and _rev onto whatever it is given, and a retained _rev from an earlier attempt would make the next one conflict.

Match records holding the given enum value, whether stored as a single value or inside an array (multi-select / isArray field).

Always both variants are matched, independent of the field's current isArray setting, because that can be toggled in the admin UI while existing records still hold values in the previous shape (same approach as EntityFilter). A plain equality selector alone does not match array values in CouchDB's Mango _find (unlike client-side, where ucast treats it as "array contains"), so $elemMatch is needed for online-only mode (#4406).

Build export column resolvers for all fields in a schema.

Iterates the schema, looks up each field's datatype, and collects the columns the datatype contributes via getExportColumns.

Create a MatchingSideConfig object and fill it with columns from comparison array if necessary

Create a form validator that checks a single field's value against the permission rule conditions restricting it, so that users see a normal field error instead of only a technical rejection when saving.

The rules are evaluated in the given priority order (as returned by ability.rulesFor): the first rule whose condition matches the value decides, mirroring CASL's own precedence.

Returns null if the field's value cannot be the reason for a denied save. Inverted ("cannot") rules with conditions on several fields and conditions on properties without a form control (e.g. "created.by") are not covered here and remain handled by the save-time permission check.

Human-readable summary of a single permission condition fragment (the value of one key in a CASL rule's conditions object).

Validator to ensure a field becomes readonly after it has been saved once.

Wraps Vitest lifecycle and test callbacks in Angular's ProxyZone when it is available.

Angular test utilities such as waitForAsync() and fakeAsync() still rely on Zone context even when the test runner is Vitest. This patch keeps those helpers working without rewriting every existing spec immediately.

Helper function to remove custom schema fields from Entity that have been created using getDefaultInheritedForm().

Helper function to add some custom schema fields to Entity for testing. Use in combination with a call to cleanUpTemporarySchemaFields() in afterEach.

Remove the "last sync" marker of every database, so that no previous sync is assumed to have happened on this device.

This accesses the real localStorage directly rather than the injectable LOCAL_STORAGE_TOKEN, because it also runs before Angular exists. Callers that need this mockable should wrap it in an instance method first.

Run pending reset cleanup before Angular bootstraps. Called from main.ts so that IndexedDB databases are deleted while no PouchDB connections are open (eliminating race conditions).

Close the mat-menu of the given menu trigger and stop propagation of the event to avoid closing parent menus as well.

Recursively collect every query string value from a report definition tree.

Whether a report's results should be rendered as a hierarchical group/count table (sql-v2-table) rather than a flat tabular table (object-table).

Derived purely from the canonical config structure (no version flag): a report is hierarchical when its reportDefinition contains a group (groupTitle) or more than one top-level item; otherwise it is tabular. Legacy v1 configs (normalized to a single ungrouped query) resolve to tabular.

Whether running this report offers a date-range (start & end date) input, derived from the date placeholders used in its queries so it stays in sync with the actual report definition:

• "sql": the query uses the $startDate / $endDate placeholders.
• "reporting"/"exporting": the in-browser query uses positional ? placeholders (date args).

Combine the given conditions so that all of them have to be met.

Conditions without any content are left out, because an empty object as an $and branch makes a database query match no document at all, and $and is dropped entirely when it is not needed. Use this instead of merging conditions into one object, which would silently overwrite a key (like $or) that more than one of them uses.

Compare dates at day precision

Handles special cases like ConfigurableEnum objects and Dates. Used for filter evaluation and conditional color matching.

This utility is kept separate to avoid circular dependencies between Entity and FilterService.

-1 if a < b, 0 if a === b, 1 if a > b

Custom sort implementation for a MatTableDataSource<TableRow>

the sorted table rows

Compute new-format database names (using Keycloak UUID + dash separator). Used after migration to the "indexeddb" adapter.

Compute legacy-format database names (username for app, underscore for notifications). Used with the old "idb" adapter before migration.

Recursively converts any $regex value in an object to a CouchDB inline (?i) pattern.

The transformed query object.

Converts an Angular DatePipe format string to the equivalent Moment.js format string. Angular uses lowercase tokens (dd, yyyy), Moment.js uses uppercase (DD, YYYY). Exported for testing only.

Set the global date format at runtime based on configuration. This is called by SiteSettingsService during initialization.

Creates an age range validator (min or max age).

Validator for maximum age.

Validator for minimum age.

Creates a custom colored marker icon using Leaflet's DivIcon. This approach ensures accurate color representation for all colors, overcoming the limitations of the hue-rotate filter which cannot properly handle achromatic colors or accurately represent all RGB values.

Based on: https://stackoverflow.com/a/40870439/1473411

Leaflet DivIcon with the specified color

Calculate distance between two points Source ://henry-rossiter.medium.com/calculating-distance-between-geographic-coordinates-with-javascript-5f3097b61898https

Get all properties of an entity that represent a geographic location

Calculate the minimum distance (km) between an entity's location fields and a list of comparison coordinates. Returns null if no distance can be computed.

Creates a date range validator (min or max).

Validator for maximum date.

Validator for minimum date.

Normalizes a date to just the date portion (no time).

Parses a value to a Date object. Handles Date objects, date strings (YYYY-MM-DD), timestamps, and special value "$now".

"Simulate" a custom entity type that saves all fields without transformations through a mocked EntitySchema.

This is a utility function to help demo data creation because the dynamically migrated config is not ready at the time of demo data generation yet.

An in-memory stand-in for localStorage, to be provided for LOCAL_STORAGE_TOKEN in tests.

Prefer this over vi.spyOn(Storage.prototype, ...): Storage.prototype lives in the worker process rather than the module registry, so Vitest's isolate does not undo such a stub. An unrestored one leaks into every later spec file and silently makes unrelated tests read a fake localStorage.

Decorator (Annotation @DatabaseEntity()) to set the string ENTITY_TYPE to an Entity Type. The entity should also be added to the databaseEntities array of the surrounding module.

also see

Human-readable, but stable across occurrences of the same problem.

Add more human-readable descriptions to Sentry breadcrumbs for debugging.

see https://docs.sentry.io/platforms/javascript/enriching-events/breadcrumbs/

Enrich events with structured extra data from custom Error properties (e.g. DatabaseException's entityId, status, reason).

Reduce an error message to a grouping key.

On top of normalizeErrorValue this also removes differences that carry no meaning but do split issues, as third-party libraries are not consistent about them: PouchDB reports both "Unauthorized" and "unauthorized", and both "Document update conflict" and "Document update conflict." (with a period) for the same failure.

Collect all failures that are really "the app could not reach the server" into a single issue.

These are raised by the browser (and by third-party libraries wrapping it) at whatever point a request happened to be made, so grouping them by stack trace produces an open-ended stream of near-identical issues that all have the same (non-)answer. They still have to be reported rather than dropped, because a server outage surfaces exactly this way - but as one issue whose event count is the interesting signal.

The browsers' differing wordings ("Failed to fetch" / "Load failed" / ...) would make the title flip-flop between events of the merged issue, so it is replaced by a stable one and kept as a searchable tag instead.

Group by the error chain instead of the stack trace, so that one problem shows up as one issue.

exception.values is ordered innermost-first: values[0] is the deepest cause, the originally thrown error is last. Both ends matter - the thrown error says which operation failed, the root cause says why (e.g. a config load failing because the device is offline is a different problem from the same load failing because the user is unauthorized).

The error the event is grouped by is usually the thrown one, but can be a link further down the chain when the ones above it add nothing (see rewrappedCauseGroupedError and loggedUnreachableServer).

Because the root cause is part of the grouping key, it is also appended to the reported message: otherwise several issues share one title (a dozen "Failed to load configuration from the database." rows) and can only be told apart by opening each of them.

The route remains available as the transaction tag, so a failure can still be filtered by where it happened without splitting it into separate issues.

The part of an error message that identifies the problem.

Set an explicit grouping fingerprint where Sentry's default grouping splits one problem across many issues.

Sentry groups by stack trace whenever one is available. That is the right default for a bug in application code, but not for a failure that is raised from one central place and reached from many components, routes and async call sites - the stack then differs per caller and even per build (releases without source maps report minified frames), so one problem scatters across a dozen issues that each have to be triaged separately, and archiving one of them does not silence the others.

The cases are checked most-specific first: an error we recognize by name says more about what went wrong than the fact that a network request failed underneath it, so those keep their own issues instead of being absorbed into the shared network bucket.

Whether the reported error carries the HTTP status of a request that never reached the backend - a gateway error names the problem in its status rather than in a message isConnectivityException could recognize.

Event-level, because the status describes the error that was captured (it is attached by enrichSentryEvent) rather than one link of its chain.

Whether the reported error is (or was caused by) the server rejecting an expired access token that could not be renewed.

RemotePouchDatabase renews the session and repeats such a request, so this only surfaces while the login server cannot be reached - a transient state the user is told about there, which says nothing about the code that happened to be waiting for the data. Filtering it here spares every consumer of the database from having to recognize it (whether it logs the failure, wraps it or lets it go unhandled).

The trade-off is deliberate: a consumer that mishandles a failed load is not reported while the failure is an expired session (only through other causes, e.g. connectivity). This also applies to errors that merely wrap it, like a ConfigLoadError - which tells the user and reloads the app itself. Other 401 reasons (e.g. an invalid token signature) are still reported, see isExpiredSessionError.

The original error is inspected rather than the serialized event, as that loses the status and reason of a wrapped DatabaseException.

Whether one link of a reported error chain is a connectivity failure.

Whether the reported error is a rejected write whose revision was out of date.

Two users editing one record is normal operation for an offline-first app, not a fault: the save is rejected, the user is told so by the form that attempted it, and the occurrence is counted in usage analytics instead (see PouchDatabase.reportConflict). Reporting it here on top of that produced a steady stream of issues nobody could act on - at error level, so louder than the failures that do need attention.

The trade-off is deliberate: how often conflicts happen is now only visible in usage analytics, not in error monitoring.

Count occurrences of an event and check whether it exceeded the session cap.

The budget is one per issue (see repeatKey), so that a device running into several problems at once still reports each of them. Keying it more coarsely - by the root cause the issues have in common - starves them instead: in an offline-first app a single connectivity failure is the root cause of the config load, the permission rules, the sync and every file download alike, so whichever of them failed first would silence all the others for that session.

Note that the cap therefore also limits how much an issue's event count says about the volume of a problem - it shows that it occurs, not how often.

Whether the event is a network-layer fetch failure that occurred while the device was offline. In an offline-first app this is a normal state without diagnostic value (server outages still surface through online users).

The failed request that a LoggedError directly wraps, if that is all it has to report.

The message an error is logged with says where it happened ("Failed to load important notes"), which for most errors is what tells two problems apart. For a request that never reached the server it is not: the connection failed, and every component loading data at that moment logs it under a message of its own. Grouped by those, a single connectivity drop opens one issue per component - next to the issue the same failure already has where it is reported without a message. Grouping them by the wrapped error puts them into that one issue instead; the logged message is kept as a tag, and the route is still the transaction tag.

Only an error of a recognized type (see CAUSE_GROUPED_ERROR_TYPES) directly below the wrapper qualifies:

• a named error in between (a ConfigLoadError caused by a failed fetch) says more than the fact that a request failed, and keeps its own issue;
• any other failed request has no issue of its own to go to, only the shared network bucket - where a chunk that did not load during bootstrap, so that the app never started, would disappear among requests of no consequence.

The text of anything that was passed to the logger as its "message".

Mask volatile details (ids, urls, numbers) so that different occurrences of the same problem produce the same string.

Stays human-readable, as it is also used to describe the root cause in the issue title (see describeCause).

Sentry beforeSend hook: drops network failures of offline devices and excessive repeats of an identical event, and enriches the remaining events with structured extra data and a stable grouping fingerprint.

Grouping runs before the repeat cap because the cap is applied per issue, which is what the fingerprint defines (see isExcessiveRepeat).

Which registration a registry error is about, if there is one in the chain.

The key is not part of the error message, so that all keys of one registry share one issue (see RegistryLookupError) - this is what still names it in each report. The cause chain is searched as well, because Angular re-throws an error raised in a resource() loader as an error of its own (see rewrappedCauseGroupedError), which does not carry the key.

The issue an event will end up in, as far as it is known here: the fingerprint is exactly what separates issues, and for the events that keep Sentry's stack-based grouping the thrown error is the closest stand-in (deliberately without any stack information, so that an error loop is capped even where the frames differ between occurrences).

Replace the reported message by one that does not depend on which browser (or library) sent the event, keeping the original one available as extra data.

Report an exception under the normalized message it is grouped by, keeping the original one as extra data.

Sentry titles an issue by the reported message, so the volatile details that fingerprintKey masks out of the grouping key are still what the issue list shows: one row per document id, and a response body quoted into an error message (an nginx error page, say) pushing every other row off the screen. Only used where the message is the grouping key anyway, so that the title of an issue and the reason its events are in it cannot drift apart.

Clear the repeat budget that isExcessiveRepeat keeps per app session.

Exported for tests: nothing else resets those counters, so without this every spec in a file shares one budget and whichever runs last sees its events dropped instead of processed - which is easy to mistake for the behaviour under test, as the budget is shared by all events of one issue.

The error of a recognized type (see CAUSE_GROUPED_ERROR_TYPES) that a framework re-threw as a generic one, if that is what this chain is.

Angular does this for an error raised inside a resource() loader: it wraps it in an error of its own that copies the original's message and whose type is the plain "Error" a subclass inherits. The wrapper contributes nothing but a different stack trace, so grouping by it opens a separate issue per call site for exactly the problem that groupByErrorChain keeps as one.

Only a wrapper that repeats the recognized error's message counts as such. One that says what it was doing ("Failed to load configuration from the database.") describes the failure better than its cause does, and stays the error the event is grouped by.

The Error to report for a log call: an error that was logged directly is reported as it is, anything else is wrapped in a LoggedError.

Extract the diagnostic fields of a fetch Response into a plain object.

Response keeps its state in internal slots rather than own enumerable properties, so passing one to the logger (or to JSON.stringify) yields an empty object - the reported event then carries no status at all, which is the one thing needed to tell e.g. a conflict from a rate limit (see AAM-DIGITAL-77H, whose context reads [{}] for every event).

The method is not part of the Response and has to be passed in, but it decides how a report should be read: the same status means different things for a read and for a write (a 409 on a PUT is a rejected save, on a _local checkpoint it is replication housekeeping), so without it an event cannot be classified at all - which is why the AAM-DIGITAL-77H events from before this was recorded remain unclassifiable.

The message to report for an unexpected response from a database request.

Deliberately says "response" rather than "fetch": one code path carries both reads and writes, and calling a rejected write a failed fetch is what sent the first analysis of AAM-DIGITAL-77H down the wrong path.

The fallback is digit-free so that it is not mangled by the number masking described on UNEXPECTED_STATUS_NAMES.

Remove empty (null / undefined) entries from the groups' field lists.

These are not a valid ColumnConfig and only ever come from a malformed config, but every consumer dereferences them (toFormFieldConfig(field).id) and would throw on the whole editor. Dropping them here keeps the rest of the configuration editable so the admin can repair it.

Move field from one drop target to another, returning new group objects for the groups that changed (all others are kept as they are).

A target of "available" is the toolbar of fields not used in the form: it holds no state of its own (it is derived from the form's groups), so a field moved there is simply removed from the form and a field moved from there is simply added.

The most specific place name available for an address.

The given author as an entity id, or undefined when it is not one. An entity id is type-prefixed, which a plain username is not.

Compares two entity ids where one or both may be missing the Type: prefix (e.g. a legacy exact_username stored without it), treating them as equal when they refer to the same record.

Exported for reuse wherever a stored/session entity id needs to be compared against a value coming from an entity picker (which always includes the prefix).

Detect IndexedDB/PouchDB corruption symptoms commonly observed when the app is used in multiple tabs with concurrent writes.

We intentionally match on transaction was aborted because this is the reliable signal present on the actual error object propagated to app code after IndexedDB global-failure cases. The unknown_error label is too generic and may appear for unrelated failures.

Escape all special regex characters so the given text can be used as a literal search string inside a regular expression.

Assert that two arrays contain the same items, regardless of order, while still supporting asymmetric matchers such as expect.objectContaining(...).

properties of a rule beyond subject/action/conditions (e.g. reason), or undefined if none

group a row's allowed actions by identical conditions + extra properties

Convert permission rules into the matrix model. Rules for the same subject are merged, with later rules winning per action.

Extract a group ID from a group value (string, object, etc.)