@simplysf/simply-sobject-core

Field history object derivation/filtering and relationship-field discovery. This is not a Salesforce CLI plugin — it's the library layer behind @simplysf/simply-sobject's field-history and backup commands, published separately so it can be imported directly by anything that wants the same logic (an editor extension, a CI job, a script) without pulling in the CLI framework.

Install

npm install @simplysf/simply-sobject-core

Requires Node.js >=22 and either "type": "module" or a dynamic import() — this package ships ESM only.

API

Everything below is exported from the package root. Removing or renaming an export is a breaking change; see src/index.ts.

| Export | Description | | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | getHistoryObjectName(sobject) | Derives a field history object's API name for a tracked sobject (e.g. Account → AccountHistory). | | getParentIdField(sobject) | Derives a field history object's lookup field back to its parent record. | | buildWhereClause(filter, parentFieldName, soqlFilterableFields) | Builds a SOQL WHERE clause from the SOQL-filterable subset of a filter tree. | | recordMatchesClientFilters(record, filter, parentFieldName, soqlFilterableFields) | Evaluates the non-SOQL-filterable subset of a filter tree against a queried record. | | discoverRelationshipFields(connection, fields) | Discovers identifying-field relationship paths (e.g. RecordType.Name) for an SObject's describe result. | | buildFieldHistorySchemaReportHtml(options) | Pure function: renders a self-contained HTML report of field-history-tracked objects/fields. | | FilterConditionSchema, FilterGroupSchema, FilterConfigSchema | zod schemas for parsing/validating a filter tree (the JSON shape simply sobject history commands' --filter flag accepts). | | FilterCondition, FilterGroup, FilterConfig, FieldHistorySchemaEntry, GroupedFieldHistorySchemaData | Supporting types. |

import { getHistoryObjectName, getParentIdField } from '@simplysf/simply-sobject-core';

getHistoryObjectName('Opportunity'); // 'OpportunityFieldHistory'
getParentIdField('My_Object__c'); // 'ParentId'

import { FilterConfigSchema, buildWhereClause, recordMatchesClientFilters } from '@simplysf/simply-sobject-core';

const filter = FilterConfigSchema.parse(JSON.parse(rawJson));
const whereClause = buildWhereClause(filter, 'AccountId', new Set(['AccountId', 'CreatedDate']));
// ...run the query, then for each returned record:
const included = recordMatchesClientFilters(record, filter, 'AccountId', new Set(['AccountId', 'CreatedDate']));

import { discoverRelationshipFields } from '@simplysf/simply-sobject-core';

const describeResult = await connection.describe('Account');
const relationshipPaths = await discoverRelationshipFields(connection, describeResult.fields);

Issues

Please report any issues at https://github.com/SimplySF/simply-plugins-core/issues

Contributing

This package is part of the @simplysf/simply monorepo. See CONTRIBUTING.md for what's specific to this package, and the repo's root CONTRIBUTING.md for repo structure, setup, commit conventions, and how to submit a pull request. Please also read our Code of Conduct.

License

Licensed under the Apache-2.0 license.