@decafhub/decaf-client-extras 0.0.5 → 0.1.1

package/reports/valuation/-remote-valuation-report-shared.js

@@ -22,7 +22,7 @@ function toArtifact(x) {
         symbol: x.symbol,
         name: (0, prelude_1.sanitizedNonEmptyText)(x.name),
         ccy: prelude_1.Maybe.fromNullable(x.ccy),
-        quantity: (0, prelude_1.asDecimal)(x.quantity),
+        quantity: (0, prelude_1.unsafeDecimal)(x.quantity),
         country: (0, prelude_1.sanitizedNonEmptyText)(x.country),
         issuer: (0, prelude_1.sanitizedNonEmptyText)(x.issuer),
         sector: (0, prelude_1.sanitizedNonEmptyText)(x.sector),
@@ -38,14 +38,17 @@ exports.toArtifact = toArtifact;
 function toAccrual(x) {
     return {
         name: x.name,
-        value: (0, prelude_1.asDecimal)(x.value),
+        value: (0, prelude_1.unsafeDecimal)(x.value),
         accounts: x.accounts.map(function (y) { return ({
             account: y.account,
-            value: (0, prelude_1.asDecimal)(y.value),
+            value: (0, prelude_1.unsafeDecimal)(y.value),
             accruals: y.accruals.map(function (z) { return ({
                 artifact: toArtifact(z.artifact),
                 ccy: z.ccy,
-                value: { org: (0, prelude_1.asDecimal)(z.value.org || 0), ref: (0, prelude_1.asDecimal)(z.value.ref || 0) },
+                value: {
+                    org: (0, prelude_1.decimalFromNullable)(z.value.org).orDefault(prelude_1.zero),
+                    ref: (0, prelude_1.decimalFromNullable)(z.value.ref).orDefault(prelude_1.zero),
+                },
             }); }),
         }); }),
     };
@@ -53,22 +56,22 @@ function toAccrual(x) {
 exports.toAccrual = toAccrual;
 function toOrgRef(x) {
     return {
-        org: (0, prelude_1.maybeDecimal)(x.org).orDefault(prelude_1.zero),
-        ref: (0, prelude_1.maybeDecimal)(x.ref).orDefault(prelude_1.zero),
+        org: (0, prelude_1.decimalFromNullable)(x.org).orDefault(prelude_1.zero),
+        ref: (0, prelude_1.decimalFromNullable)(x.ref).orDefault(prelude_1.zero),
     };
 }
 exports.toOrgRef = toOrgRef;
 function toMaybeOrgRef(x) {
     return prelude_1.Maybe.fromNullable(x).chain(function (_a) {
         var org = _a.org, ref = _a.ref;
-        return (0, prelude_1.maybeDecimal)(org).chain(function (o) { return (0, prelude_1.maybeDecimal)(ref).chain(function (r) { return (0, prelude_1.Just)({ org: o, ref: r }); }); });
+        return (0, prelude_1.decimalFromNullable)(org).chain(function (o) { return (0, prelude_1.decimalFromNullable)(ref).chain(function (r) { return (0, prelude_1.Just)({ org: o, ref: r }); }); });
     });
 }
 exports.toMaybeOrgRef = toMaybeOrgRef;
 function toBaseHolding(nav, x) {
     return {
         artifact: toArtifact(x.artifact),
-        quantity: (0, prelude_1.asDecimal)(x.quantity),
+        quantity: (0, prelude_1.unsafeDecimal)(x.quantity),
         investment: {
             px: toOrgRef(x.investment.px),
             txncosts: toMaybeOrgRef(x.investment.txncosts),
@@ -87,12 +90,12 @@ function toBaseHolding(nav, x) {
                 abs: toOrgRef(x.valuation.exposure.abs),
             },
         },
-        valuePercentage: (0, prelude_1.safeDiv)((0, prelude_1.maybeDecimal)(x.valuation.value.net.ref).orDefault(prelude_1.zero), nav),
-        netExposurePercentage: (0, prelude_1.safeDiv)((0, prelude_1.maybeDecimal)(x.valuation.exposure.net.ref).orDefault(prelude_1.zero), nav),
-        absExposurePercentage: (0, prelude_1.safeDiv)((0, prelude_1.maybeDecimal)(x.valuation.exposure.abs.ref).orDefault(prelude_1.zero), nav),
-        change: (0, prelude_1.maybeDecimal)(x.change),
-        pnl: (0, prelude_1.maybeDecimal)(x.pnl).orDefault(prelude_1.zero),
-        pnlToInvestment: (0, prelude_1.maybeDecimal)(x.pnl_to_investment),
+        valuePercentage: (0, prelude_1.safeDiv)((0, prelude_1.decimalFromNullable)(x.valuation.value.net.ref).orDefault(prelude_1.zero), nav),
+        netExposurePercentage: (0, prelude_1.safeDiv)((0, prelude_1.decimalFromNullable)(x.valuation.exposure.net.ref).orDefault(prelude_1.zero), nav),
+        absExposurePercentage: (0, prelude_1.safeDiv)((0, prelude_1.decimalFromNullable)(x.valuation.exposure.abs.ref).orDefault(prelude_1.zero), nav),
+        change: (0, prelude_1.decimalFromNullable)(x.change),
+        pnl: (0, prelude_1.decimalFromNullable)(x.pnl).orDefault(prelude_1.zero),
+        pnlToInvestment: (0, prelude_1.decimalFromNullable)(x.pnl_to_investment),
         opendate: x.opendate,
         lastdate: x.lastdate,
     };
@@ -115,7 +118,7 @@ exports.toHolding = toHolding;
  * report.
  */
 function recompileBaseValuationReport(x) {
-    var nav = (0, prelude_1.maybeDecimal)(x.nav).orDefault(prelude_1.zero);
+    var nav = (0, prelude_1.decimalFromNullable)(x.nav).orDefault(prelude_1.zero);
     var report = {
         asof: x.reported,
         date: x.asof,
@@ -124,20 +127,20 @@ function recompileBaseValuationReport(x) {
         accounts: x.accounts,
         holdings: x.holdings.map(function (rh) { return toHolding(nav, rh); }),
         accruals: x.accruals.map(toAccrual),
-        fxRates: x.fxrates.map(function (r) { return ({ ccy1: r.ccy1, ccy2: r.ccy2, value: (0, prelude_1.asDecimal)(r.value), asof: r.asof }); }),
+        fxRates: x.fxrates.map(function (r) { return ({ ccy1: r.ccy1, ccy2: r.ccy2, value: (0, prelude_1.unsafeDecimal)(r.value), asof: r.asof }); }),
         figures: {
-            investment: (0, prelude_1.maybeDecimal)(x.investment).orDefault(prelude_1.zero),
+            investment: (0, prelude_1.decimalFromNullable)(x.investment).orDefault(prelude_1.zero),
             valuation: {
-                net: (0, prelude_1.maybeDecimal)(x.valuation_net).orDefault(prelude_1.zero),
-                abs: (0, prelude_1.maybeDecimal)(x.valuation_abs).orDefault(prelude_1.zero),
+                net: (0, prelude_1.decimalFromNullable)(x.valuation_net).orDefault(prelude_1.zero),
+                abs: (0, prelude_1.decimalFromNullable)(x.valuation_abs).orDefault(prelude_1.zero),
             },
-            accrued: (0, prelude_1.maybeDecimal)(x.accrued).orDefault(prelude_1.zero),
-            liabilities: (0, prelude_1.maybeDecimal)(x.liabilities).orDefault(prelude_1.zero),
-            gav: (0, prelude_1.maybeDecimal)(x.gav).orDefault(prelude_1.zero),
+            accrued: (0, prelude_1.decimalFromNullable)(x.accrued).orDefault(prelude_1.zero),
+            liabilities: (0, prelude_1.decimalFromNullable)(x.liabilities).orDefault(prelude_1.zero),
+            gav: (0, prelude_1.decimalFromNullable)(x.gav).orDefault(prelude_1.zero),
             nav: nav,
-            aum: (0, prelude_1.maybeDecimal)(x.aum).orDefault(prelude_1.zero),
-            pnl: (0, prelude_1.maybeDecimal)(x.pnl).orDefault(prelude_1.zero),
-            pnlToInvestment: (0, prelude_1.maybeDecimal)(x.pnl_to_investment),
+            aum: (0, prelude_1.decimalFromNullable)(x.aum).orDefault(prelude_1.zero),
+            pnl: (0, prelude_1.decimalFromNullable)(x.pnl).orDefault(prelude_1.zero),
+            pnlToInvestment: (0, prelude_1.decimalFromNullable)(x.pnl_to_investment),
         },
     };
     return (0, prelude_1.Right)(report);

package/reports/valuation/-valuation-report-holdings-tree/-machinery.js

@@ -38,13 +38,11 @@ var __values = (this && this.__values) || function(o) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeValuationReportHoldingsTree = exports.addValuationReportHoldingToTree = exports.makeValuationReportHoldingsTreeNode = exports.retreatTree = exports.resortChildren = exports.updateTotals = exports.makeValuationReportHoldingsTreeNodeValue = void 0;
 var prelude_1 = require("@telostat/prelude");
-var purify_ts_1 = require("purify-ts");
-var List_1 = require("purify-ts/List");
 var _utils_1 = require("./-utils");
 function makeValuationReportHoldingsTreeNodeValue() {
     return {
         investment: prelude_1.zero,
-        accrued: purify_ts_1.Nothing,
+        accrued: prelude_1.Nothing,
         netValue: prelude_1.zero,
         netValueRatio: prelude_1.zero,
         absValue: prelude_1.zero,
@@ -73,10 +71,10 @@ function updateTotals(nav, investment, tree) {
     var pnl = (0, prelude_1.sumDecimals)(holdings.map(function (x) { return x.pnl; })).add((0, prelude_1.sumDecimals)(children.map(function (x) { return x.totals.pnl; })));
     var accruedsHoldings = holdings.map(function (x) { return x.investment.accrued.map(function (x) { return x.ref; }); });
     var accruedsChildren = children.map(function (x) { return x.totals.accrued; });
-    var accrueds = purify_ts_1.Maybe.catMaybes(__spreadArray(__spreadArray([], __read(accruedsHoldings), false), __read(accruedsChildren), false));
+    var accrueds = prelude_1.Maybe.catMaybes(__spreadArray(__spreadArray([], __read(accruedsHoldings), false), __read(accruedsChildren), false));
     return {
         investment: (0, prelude_1.sumDecimals)(holdings.map(function (x) { return x.investment.value.ref; })).add((0, prelude_1.sumDecimals)(children.map(function (x) { return x.totals.investment; }))),
-        accrued: accrueds.length === 0 ? purify_ts_1.Nothing : (0, purify_ts_1.Just)((0, prelude_1.sumDecimals)(accrueds)),
+        accrued: accrueds.length === 0 ? prelude_1.Nothing : (0, prelude_1.Just)((0, prelude_1.sumDecimals)(accrueds)),
         netValue: netValue,
         netValueRatio: (0, prelude_1.safeDiv)(netValue, nav).orDefault(prelude_1.zero),
         absValue: absValue,
@@ -93,11 +91,11 @@ exports.updateTotals = updateTotals;
 function resortChildren(node) {
     return node.children.sort(function (t1, t2) {
         // Get current address segments:
-        var segment1 = List_1.List.last(t1.address);
-        var segment2 = List_1.List.last(t2.address);
+        var segment1 = prelude_1.List.last(t1.address);
+        var segment2 = prelude_1.List.last(t2.address);
         // Compare and return:
         return segment1
-            .chain(function (s1) { return segment2.chain(function (s2) { return (0, purify_ts_1.Just)((0, prelude_1.Tuple)(s1, s2)); }); })
+            .chain(function (s1) { return segment2.chain(function (s2) { return (0, prelude_1.Just)((0, prelude_1.Tuple)(s1, s2)); }); })
             .map(function (x) { return x.toArray(); })
             .map(function (_a) {
             var _b = __read(_a, 2), x = _b[0], y = _b[1];
@@ -118,7 +116,7 @@ function retreatTree(nav, investment, tree) {
 exports.retreatTree = retreatTree;
 function makeValuationReportHoldingsTreeNode(address) {
     return {
-        name: List_1.List.last(address)
+        name: prelude_1.List.last(address)
             .map(function (x) { return x.name; })
             .orDefault(''),
         address: address,

package/reports/valuation/-valuation-report-portfolio.d.ts

@@ -1,5 +1,5 @@
 import { Decimal, Maybe, SDate, SDateTime } from '@telostat/prelude';
-import { ActionId, CurrencyCode, ExternalValuationId, OhlcSeriesId, PortfolioId, PrincipalId, ShareClassFeeScheduleId, ShareClassId } from '../../commons';
+import { DecafActionId, CurrencyCode, DecafExternalValuationId, DecafOhlcSeriesId, DecafPortfolioId, DecafPrincipalId, DecafShareClassFeeScheduleId, DecafShareClassId } from '../../commons';
 import { BaseValuationReport, ValuationReportPortfolio } from './-valuation-report-shared';
 export interface PortfolioValuationReport extends BaseValuationReport {
     portfolio: ValuationReportPortfolio;
@@ -24,13 +24,13 @@ export interface PortfolioValuationReportShareClassValue {
     ytdInt: Maybe<Decimal>;
 }
 export interface PortfolioValuationReportShareClass {
-    id: ShareClassId;
+    id: DecafShareClassId;
     created: SDateTime;
-    creator: Maybe<PrincipalId>;
+    creator: Maybe<DecafPrincipalId>;
     updated: SDateTime;
-    updater: Maybe<PrincipalId>;
+    updater: Maybe<DecafPrincipalId>;
     guid: string;
-    portfolio: PortfolioId;
+    portfolio: DecafPortfolioId;
     name: string;
     currency: CurrencyCode;
     isin: Maybe<string>;
@@ -42,22 +42,22 @@ export interface PortfolioValuationReportShareClass {
     subscriptionRedemptionPeriod: Maybe<string>;
     managementFeeFrequency: Maybe<number>;
     performanceFeeFrequency: Maybe<number>;
-    benchmark: Maybe<OhlcSeriesId>;
+    benchmark: Maybe<DecafOhlcSeriesId>;
     description: Maybe<string>;
-    feeScheduleIds: ShareClassFeeScheduleId[];
-    effectiveFeeScheduleId: Maybe<ShareClassFeeScheduleId>;
-    subscriptionIds: ActionId[];
+    feeScheduleIds: DecafShareClassFeeScheduleId[];
+    effectiveFeeScheduleId: Maybe<DecafShareClassFeeScheduleId>;
+    subscriptionIds: DecafActionId[];
     outstanding: Maybe<Decimal>;
 }
 export interface PortfolioValuationReportExternalValue {
-    id: ExternalValuationId;
+    id: DecafExternalValuationId;
     created: SDateTime;
-    creator: Maybe<PrincipalId>;
+    creator: Maybe<DecafPrincipalId>;
     updated: SDateTime;
-    updater: Maybe<PrincipalId>;
+    updater: Maybe<DecafPrincipalId>;
     guid: string;
-    portfolio: PortfolioId;
-    shareclass: Maybe<ShareClassId>;
+    portfolio: DecafPortfolioId;
+    shareclass: Maybe<DecafShareClassId>;
     date: SDate;
     ccy: CurrencyCode;
     shares: Maybe<Decimal>;

package/reports/valuation/-valuation-report-shared.d.ts

@@ -1,5 +1,5 @@
 import { Decimal, Maybe, SDate, SDateTime } from '@telostat/prelude';
-import { AccountId, ArtifactId, ArtifactTypeId, CurrencyCode, DateType, PortfolioId } from '../../commons';
+import { CurrencyCode, DateType, DecafAccountId, DecafArtifactId, DecafArtifactTypeId, DecafPortfolioId } from '../../commons';
 /**
  * Type definition for base valuation report.
  */
@@ -31,7 +31,7 @@ export interface BaseValuationReport {
  * Type definition for account reference in valuation reports.
  */
 export interface ValuationReportAccount {
-    id: AccountId;
+    id: DecafAccountId;
     guid: string;
     name: string;
 }
@@ -39,7 +39,7 @@ export interface ValuationReportAccount {
  * Type definition for portfolio reference in valuation reports.
  */
 export interface ValuationReportPortfolio {
-    id: PortfolioId;
+    id: DecafPortfolioId;
     guid: string;
     name: string;
 }
@@ -155,7 +155,7 @@ export interface ValuationReportAccrualByCurrency {
  * Type definition of the FINREA artifact type.
  */
 export interface ValuationReportArtifactType {
-    id: ArtifactTypeId;
+    id: DecafArtifactTypeId;
     name: string;
     order: number;
 }
@@ -163,7 +163,7 @@ export interface ValuationReportArtifactType {
  * Type definition for the artifact as reported in the valuation.
  */
 export interface ValuationReportArtifact {
-    id: ArtifactId;
+    id: DecafArtifactId;
     guid: string;
     type: ValuationReportArtifactType;
     stype: Maybe<string>;
@@ -179,7 +179,7 @@ export interface ValuationReportArtifact {
     isin: Maybe<string>;
     figi: Maybe<string>;
     expiry: Maybe<SDate>;
-    underlyingId: Maybe<ArtifactId>;
+    underlyingId: Maybe<DecafArtifactId>;
 }
 export interface ValuationReportFxRate {
     ccy1: CurrencyCode;

package/shell.nix

@@ -1,21 +1,6 @@
-with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/22.05.tar.gz) { };
+{ ... }:
 
-stdenv.mkDerivation {
-  name = "decaf-client-javascript-extras";
-
-  buildInputs = with pkgs; [
-    git
-    nodejs-16_x
-    yarn
-
-    figlet
-    lolcat
-  ];
-
-  shellHook = ''
-    ## Greet:
-    figlet -w 999 -f standard "DECAF CLIENT EXTRAS DEV SHELL" | lolcat -S 179
-  '';
-
-  DECAF_JS_SKIP_POSTINSTALL = "TRUE";
-}
+let
+  nix = import ./nix { };
+in
+nix.shell

package/src/commons/-currency.test.ts

@@ -0,0 +1,27 @@
+import { Just, Nothing } from '@telostat/prelude';
+import { CurrencyCode, mkCurrencyCode, mkCurrencyCodeError, unCurrencyCode } from './-currency';
+
+describe('currency code tests', () => {
+  const inputInvalid = ['', ' ', '\n', '\r', '\t', ' \n\r\t ', ' USD', 'USD ', ' USD ', 'U SD'];
+  const inputValid = ['U', 'US', 'USD', 'USd'];
+
+  test('invalid strings are rejected by the smart constructor', () => {
+    inputInvalid.forEach((x) => expect(mkCurrencyCode(x)).toBe(Nothing));
+  });
+
+  test('invalid strings throw errors by the unsafe constructor', () => {
+    inputInvalid.forEach((x) => expect(() => mkCurrencyCodeError(x)).toThrow(/^Invalid currency code: /));
+  });
+
+  test('valid strings are accepted by the smart constructor', () => {
+    inputValid.forEach((x) => expect(mkCurrencyCode(x)).toStrictEqual(Just(x as CurrencyCode)));
+  });
+
+  test('valid strings are accepted by the unsafe constructor', () => {
+    inputValid.forEach((x) => expect(mkCurrencyCodeError(x)).toStrictEqual(x as CurrencyCode));
+  });
+
+  test('currency codes can be converted back to string', () => {
+    inputValid.forEach((x) => expect(unCurrencyCode(mkCurrencyCodeError(x))).toStrictEqual(x));
+  });
+});

package/src/commons/-currency.ts

@@ -4,27 +4,40 @@
  * @module
  */
 
-import { Just, Maybe, mkPhantom, NewTypeWithPhantom, Nothing, unPhantom } from '@telostat/prelude';
+import { Just, Maybe, Nothing } from '@telostat/prelude';
 
 /**
- * Type encoding for currency code values.
+ * Type definition for currency code values.
  *
- * A currency code is (typically) defined as all-uppercase, three letters.
+ * A currency code is (typically) defined as all-uppercase, three-letter
+ * `string`. In this library, we are particularly using the regular expression
+ * {@link REGEXP_CURRENCY_CODE} which allows any uppercase letter followed by
+ * uppercase or lowercase letters.
+ *
+ * As for the type definition: We are using a (not-so-elegant) trick called
+ * "tagged-type" to annotate the plain-vanilla `string` type to be the
+ * `CurrencyCode` (_poor man's newtype_). Note that during the runtime, all
+ * `CurrencyCode` values are simply a `string` values.
  */
-export type CurrencyCode = NewTypeWithPhantom<'CurrencyCode', string>;
+export type CurrencyCode = string & { readonly __tag: unique symbol };
+
+/**
+ * Regular expression for currency codes in our concept.
+ */
+export const REGEXP_CURRENCY_CODE = /^[A-Z][a-zA-Z]*$/;
 
 /**
  * Attempts to create a {@link CurrencyCode} value with the given currency code.
  *
- * This function returns a `Maybe` value. For the version that throws an
- * error, see {@link mkCurrencyCodeError}.
+ * This function returns a `Maybe` value. For the
+ * version that throws an error, see {@link mkCurrencyCodeError}.
  *
  * @param x A currency code represented as string.
  * @returns If the argument has leading or trailing spaces OR it is empty,
  * `Nothing` is retured, `Just` {@link CurrencyCode} otherwise.
  */
 export function mkCurrencyCode(x: string): Maybe<CurrencyCode> {
-  return x !== x.trim() || x === '' ? Nothing : Just(mkPhantom(x));
+  return REGEXP_CURRENCY_CODE.test(x) ? Just(x as CurrencyCode) : Nothing;
 }
 
 /**
@@ -40,16 +53,18 @@ export function mkCurrencyCode(x: string): Maybe<CurrencyCode> {
  */
 export function mkCurrencyCodeError(x: string): CurrencyCode {
   return mkCurrencyCode(x).orDefaultLazy(() => {
-    throw new Error(`Invalid currency code: "${x}"`);
+    throw new Error(`Invalid currency code: ${x}`);
   });
 }
 
 /**
  * Return the currency code as a string value.
  *
+ * In runtime, this is effectively the identity function.
+ *
  * @param x {@link CurrencyCode} to be extracted string from.
  * @returns Currency code as a string.
  */
 export function unCurrencyCode(x: CurrencyCode): string {
-  return unPhantom(x);
+  return x as string;
 }

package/src/commons/-datetype.test.ts

@@ -0,0 +1,10 @@
+import { DATE_TYPES } from './-datetype';
+
+describe('date-type tests', () => {
+  test('we maintain the catalogue of date-type tests', () => {
+    expect(DATE_TYPES).toStrictEqual([
+      { label: 'Trade Date', value: 'commitment' },
+      { label: 'Value Date', value: 'settlement' },
+    ]);
+  });
+});

package/src/commons/{-date-type.ts → -datetype.ts}

@@ -6,7 +6,7 @@ export type DateType = 'commitment' | 'settlement';
 /**
  * Translation table for DECAF FINREA action date types.
  */
-export const dateTypes: { label: string; value: DateType }[] = [
+export const DATE_TYPES: { label: string; value: DateType }[] = [
   { label: 'Trade Date', value: 'commitment' },
   { label: 'Value Date', value: 'settlement' },
 ];

package/src/commons/-id.test.ts

@@ -0,0 +1,27 @@
+import { DecafActionId, DecafArtifactId, DecafArtifactTypeId, mkDecafRecordId, unDecafRecordId } from './-id';
+
+describe('DECAF record identifier tests', () => {
+  test('types are aligned and inferred correctly', () => {
+    const exampleDecafArtifactId: DecafArtifactId = mkDecafRecordId(42);
+    const exampleDecafArtifactIdValue: number = unDecafRecordId(exampleDecafArtifactId);
+    expect(exampleDecafArtifactIdValue).toBe(42);
+
+    const exampleDecafActionId: DecafActionId = mkDecafRecordId(42);
+    const exampleDecafActionIdValue: number = unDecafRecordId(exampleDecafActionId);
+    expect(exampleDecafActionIdValue).toBe(42);
+
+    const exampleDecafArtifactTypeId: DecafArtifactTypeId = mkDecafRecordId('CCY');
+    const exampleDecafArtifactTypeIdValue: string = unDecafRecordId(exampleDecafArtifactTypeId);
+    expect(exampleDecafArtifactTypeIdValue).toBe('CCY');
+  });
+
+  test('type erasure works as expected', () => {
+    interface DecafArtifact {
+      id: DecafArtifactId;
+      type: DecafArtifactTypeId;
+    }
+
+    const exampleDecafArtifact: DecafArtifact = { id: mkDecafRecordId(10), type: mkDecafRecordId('CCY') };
+    expect(exampleDecafArtifact).toStrictEqual({ id: 10, type: 'CCY' });
+  });
+});

package/src/commons/-id.ts

@@ -1,72 +1,167 @@
-import { NewTypeWithPhantom } from '@telostat/prelude';
+/**
+ * This module provides a collection of DECAF record identifier type
+ * definitions. It is not exhaustive and it will be improved on an ongoing
+ * basis.
+ *
+ * Typically, a DECAF record identifier is either number or string. Some DECAF
+ * API endoints can consume string values even though a number is expected. We
+ * are sticking here to the original type: No `number | string` definitions.
+ *
+ * Methodologically, we are using a type trick to emulate newtypes in this
+ * module: For example, DECAF artifact identifier type is defined as:
+ *
+ * ```ts
+ * export type DecafArtifactId = number & { readonly __tag: unique symbol };
+ * ```
+ *
+ * In runtime, there is only a number. The `& { readonly __tag: unique symbol }`
+ * is provided to the compiler to distinguish in between `number` identifier
+ * values  which are representing different DECAF record types.
+ *
+ * The construction and deconstruction of DECAF record identifiers are done via,
+ * respecively, `mkDecafRecordId` and `unDecafRecordId`:
+ *
+ * ```ts
+ * const exampleDecafArtifactIdValue: number = unDecafRecordId(exampleDecafArtifactId);
+ * const exampleDecafArtifactId: DecafArtifactId = mkDecafRecordId(42);
+ * expect(exampleDecafArtifactIdValue).toBe(42);
+ *
+ * const exampleDecafActionId: DecafActionId = mkDecafRecordId(42);
+ * const exampleDecafActionIdValue: number = unDecafRecordId(exampleDecafActionId);
+ * expect(exampleDecafActionIdValue).toBe(42);
+ *
+ * const exampleDecafArtifactTypeId: DecafArtifactTypeId = mkDecafRecordId('CCY');
+ * const exampleDecafArtifactTypeIdValue: string = unDecafRecordId(exampleDecafArtifactTypeId);
+ * expect(exampleDecafArtifactTypeIdValue).toBe('CCY');
+ * ```
+ *
+ * To re-iterate, the runtime representation is not affected by how DECAF record
+ * identifier types are defined:
+ *
+ * ```ts
+ * interface DecafArtifact {
+ *   id: DecafArtifactId;
+ *   type: DecafArtifactTypeId;
+ * }
+ *
+ * const exampleDecafArtifact: DecafArtifact = { id: mkDecafRecordId(10), type: mkDecafRecordId('CCY') };
+ * expect(exampleDecafArtifact).toStrictEqual({ id: 10, type: 'CCY' });
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * Type definition covering all possible DECAF record identifiers based on
+ * `number` values.
+ *
+ * This type definition must be extended whenever there is a new DECAF record
+ * identifier is defined in this module.
+ */
+export type _DecafRecordIdFromNumber = DecafArtifactId | DecafActionId;
+
+/**
+ * Type definition covering all possible DECAF record identifiers based on
+ * `string` values.
+ *
+ * This type definition must be extended whenever there is a new DECAF record
+ * identifier is defined in this module.
+ */
+export type _DecafRecordIdFromString = DecafArtifactTypeId;
+
+/* Signature for overloaded `mkDecafRecordId` function consuming a `number`. */
+export function mkDecafRecordId<T extends _DecafRecordIdFromNumber>(x: number): T;
+
+/* Signature for overloaded `mkDecafRecordId` function consuming a `string`. */
+export function mkDecafRecordId<T extends _DecafRecordIdFromString>(x: string): T;
+
+/**
+ * Constructor for DECAF record identifiers.
+ *
+ * @param x Value to create DECAF record identifier from.
+ * @returns DECAF record identifier of type deduced from call-site usage.
+ */
+export function mkDecafRecordId<T>(x: any): T {
+  return x as T;
+}
+
+/* Signature for overloaded `unDecafRecordId` function producing a `number`. */
+export function unDecafRecordId<T extends _DecafRecordIdFromNumber>(x: T): number;
+
+/* Signature for overloaded `unDecafRecordId` function producing a `string`. */
+export function unDecafRecordId<K extends _DecafRecordIdFromString>(x: K): string;
 
 /**
- * Type definition for identifiers with value spaces discriminated over the
- * given phantom type.
+ * Deconstructor for DECAF record identifiers.
+ *
+ * @param x DECAF record identifier.
+ * @returns Value of the DECAF record identifier (deduced from call-site usage).
  */
-export type Id<P, V> = NewTypeWithPhantom<P, V>;
+export function unDecafRecordId<T>(x: T): any {
+  return x as unknown;
+}
 
 /**
  * Type definition for DECAF artifact identifiers.
  */
-export type ArtifactId = NewTypeWithPhantom<'DecafArtifact', string | number>;
+export type DecafArtifactId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF artifact type identifiers.
  */
-export type ArtifactTypeId = NewTypeWithPhantom<'DecafArtifactType', string>;
+export type DecafArtifactTypeId = string & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF share class identifiers.
  */
-export type ShareClassId = NewTypeWithPhantom<'DecafShareClass', string | number>;
+export type DecafShareClassId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF principal identifiers.
  */
-export type PrincipalId = NewTypeWithPhantom<'DecafPrincipal', string | number>;
+export type DecafPrincipalId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF institution identifiers.
  */
-export type InstitutionId = NewTypeWithPhantom<'DecafInstitution', string | number>;
+export type DecafInstitutionId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF team identifiers.
  */
-export type TeamId = NewTypeWithPhantom<'DecafTeam', string | number>;
+export type DecafTeamId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF portfolio identifiers.
  */
-export type PortfolioId = NewTypeWithPhantom<'DecafPortfolio', string | number>;
+export type DecafPortfolioId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF portfolio group identifiers.
  */
-export type PortfolioGroupId = NewTypeWithPhantom<'DecafPortfolioGroup', string | number>;
+export type DecafPortfolioGroupId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF account identifiers.
  */
-export type AccountId = NewTypeWithPhantom<'DecafAccount', string | number>;
+export type DecafAccountId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF OHLC series identifiers.
  */
-export type OhlcSeriesId = NewTypeWithPhantom<'DecafOhlcSeries', string | number>;
+export type DecafOhlcSeriesId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF share class fee schedule identifiers.
  */
-export type ShareClassFeeScheduleId = NewTypeWithPhantom<'DecafShareClassFeeSchedule', string | number>;
+export type DecafShareClassFeeScheduleId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF action identifiers.
  */
-export type ActionId = NewTypeWithPhantom<'DecafAction', string | number>;
+export type DecafActionId = number & { readonly __tag: unique symbol };
 
 /**
  * Type definition for DECAF external valuation identifiers.
  */
-export type ExternalValuationId = NewTypeWithPhantom<'DecafExternalValuation', string | number>;
+export type DecafExternalValuationId = number & { readonly __tag: unique symbol };

package/src/commons/index.ts

@@ -1,3 +1,6 @@
 export * from './-currency';
-export * from './-date-type';
+export * as currency from './-currency';
+export * from './-datetype';
+export * as datetype from './-datetype';
 export * from './-id';
+export * as id from './-id';