@fin.cx/chartdata 2.12.1 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/chartdata",
-  "version": "2.12.1",
+  "version": "2.13.0",
   "private": false,
   "description": "Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, and UStVA-Kennzahl mappings",
   "main": "dist_ts/index.js",
@@ -28,10 +28,10 @@
   },
   "homepage": "https://code.foss.global/fin.cx/chartdata#readme",
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.0.0",
+    "@git.zone/tsbuild": "^5.1.2",
     "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^6.3.2",
-    "@types/node": "^26.6.2"
+    "@git.zone/tstest": "^7.2.0",
+    "@types/node": "^26.6.3"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -23,6 +23,10 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
   Bemessungsgrundlagen that cannot be derived from a single account: Kz 46/47
   (§13b Abs. 1), Kz 73/74 (§13b Abs. 2 Nr. 3, under the GrEStG) and Kz 84/85
   (the other §13b Abs. 2 supplies)
+- Account roles (`accountRole`) where an account's type and HGB position do
+  not tell it apart from the others of its position: a fixed asset's sale
+  proceeds (`asset_sale_proceeds`) and the book value of a disposed fixed
+  asset (`disposal_book_value`), listed per chart by `getAccountsByRole`
 - Coverage introspection that fails loudly on mapping gaps
 - Provenance on every record
 
@@ -38,6 +42,7 @@ pnpm add @fin.cx/chartdata
 import {
   getChart,
   getAccount,
+  getAccountsByRole,
   getMappingCoverage,
   USTVA_SCENARIO_KENNZAHLEN,
 } from '@fin.cx/chartdata';
@@ -55,6 +60,15 @@ if (coverage.missing.length > 0 || coverage.unknown.length > 0) {
 }
 
 USTVA_SCENARIO_KENNZAHLEN.intraEuAcquisitionBaseStandard; // 89
+
+// a fixed asset's disposal: DATEV states a book gain net under GuV 4 and a
+// book loss under GuV 8, so the role tells the proceeds and the book value
+// apart from the other income and expenses there
+getAccount('SKR03', 2026, '8820')?.accountRole; // 'asset_sale_proceeds'
+getAccount('SKR04', 2026, '6895')?.accountRole; // 'disposal_book_value'
+getAccount('SKR03', 2026, '8400')?.accountRole; // undefined
+getAccountsByRole('SKR04', 2026, 'disposal_book_value').map((account) => account.accountNumber);
+// ['4855', '4856', '4857', '4858', '6895', '6896', '6897', '6898']
 ```
 
 ## Data Provenance and Verification

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/chartdata',
-  version: '2.12.1',
+  version: '2.13.0',
   description: 'Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, and UStVA-Kennzahl mappings'
 }

package/ts/chartdata.lookup.ts

@@ -3,6 +3,7 @@ import type {
   IChartAccount,
   IMappingCoverage,
   IScenarioKennzahlen,
+  TAccountRole,
   TChartName,
   TMappingDimension,
 } from './chartdata.types.js';
@@ -68,6 +69,18 @@ export function getAccount(
   );
 }
 
+/**
+ * The accounts of a chart with the role (`IChartAccount.accountRole`), in the
+ * chart's order. Throws for unknown chart/year combinations, as `getChart`.
+ */
+export function getAccountsByRole(
+  chart: TChartName,
+  year: number,
+  role: TAccountRole,
+): IChartAccount[] {
+  return getChart(chart, year).accounts.filter((account) => account.accountRole === role);
+}
+
 function hasMapping(account: IChartAccount, dimension: TMappingDimension): boolean {
   switch (dimension) {
     case 'ustva':

package/ts/chartdata.types.ts

@@ -2,6 +2,20 @@ export type TChartName = 'SKR03' | 'SKR04';
 
 export type TAccountType = 'asset' | 'liability' | 'equity' | 'revenue' | 'expense';
 
+/**
+ * What an account is for where its type and HGB position do not tell it apart
+ * from the other accounts of its position. A fixed asset's disposal: DATEV
+ * states a sale's book gain net under the other operating income (GuV 4) and
+ * a book loss under the other operating expenses (GuV 8), the proceeds
+ * against the book value, beside the other income and expenses there.
+ * - 'asset_sale_proceeds': what a fixed asset fetched when it was sold
+ *   ("Erlöse aus Verkäufen Sachanlagevermögen", immaterieller
+ *   Vermögensgegenstände, Finanzanlagen), a revenue account;
+ * - 'disposal_book_value': the book value a disposed fixed asset leaves the
+ *   books with ("Anlagenabgänge … (Restbuchwert …)"), an expense account.
+ */
+export type TAccountRole = 'asset_sale_proceeds' | 'disposal_book_value';
+
 /**
  * Built-in DATEV tax automatism of an account. Lines on automatik accounts
  * must carry no BU key (automatism applies) or key 40 (automatism cancelled).
@@ -26,6 +40,8 @@ export interface IChartAccount {
   accountName: string;
   accountClass: number;
   accountType: TAccountType;
+  /** what the account is for beyond its type and HGB position; unset = they say it all */
+  accountRole?: TAccountRole;
   description?: string;
   automatikFunction?: TAutomatikFunction;
   /** BU keys allowed on lines of this account ('' = none). Unset = all. */