@decafhub/decaf-client-extras 0.0.5 → 0.1.1

package/.github/workflows/release-please.yml

@@ -6,7 +6,11 @@ on:
 name: release-please
 jobs:
   release-please:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        node: [16]
+        os: [ubuntu-latest]
     steps:
       - uses: google-github-actions/release-please-action@v3
         id: release
@@ -18,7 +22,7 @@ jobs:
 
       - uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: ${{ matrix.node }}
           registry-url: 'https://registry.npmjs.org'
           cache: 'yarn'
         if: ${{ steps.release.outputs.release_created }}

package/.github/workflows/test.yml

@@ -5,13 +5,17 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        node: [14, 16, 18]
+        os: [ubuntu-latest]
     steps:
       - uses: actions/checkout@v3
 
       - uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: ${{ matrix.node }}
           registry-url: 'https://registry.npmjs.org'
           cache: 'yarn'
 

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.0.5"
+  ".": "0.1.1"
 }

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.1.1](https://github.com/teloscube/decaf-client-javascript-extras/compare/v0.1.0...v0.1.1) (2023-04-02)
+
+
+### Miscellaneous Chores
+
+* release 0.1.1 ([e5aedf7](https://github.com/teloscube/decaf-client-javascript-extras/commit/e5aedf7ac6f802da1afdafbe2e040fb455d28c82))
+
+## [0.1.0](https://github.com/teloscube/decaf-client-javascript-extras/compare/v0.0.5...v0.1.0) (2023-01-31)
+
+
+### ⚠ BREAKING CHANGES
+
+* The underlying types of DECAF record identifiers have been changed to a simpler, tagged type definitions. Call-sites should use `mkDecafRecordId` constructor and `unDecafRecordId` de-constructor OR direct type casting when producing and consuming such values.
+* We are now adopting the convention that constants are defined via all-uppercase, snake-case symbols.
+* The underlying type of CurrencyCode has been changed to a simpler, tagged type definition. Call-sites should use either of:
+
+### Code Refactoring
+
+* change type of CurrencyCode, use regexp for validation ([b4915aa](https://github.com/teloscube/decaf-client-javascript-extras/commit/b4915aace037ce9e56be9161ea730529a7d31536))
+* change type of DECAF record identifiers ([a2f48c0](https://github.com/teloscube/decaf-client-javascript-extras/commit/a2f48c00525714ffa20ecdca2900b842581ede43))
+* rename constant dateTypes to DATE_TYPES ([7801283](https://github.com/teloscube/decaf-client-javascript-extras/commit/7801283bdc72463bbb243f03c5bb10ef77c5dd7a))
+
 ## [0.0.5](https://github.com/teloscube/decaf-client-javascript-extras/compare/v0.0.4...v0.0.5) (2022-12-28)
 
 

package/commons/-currency.d.ts

@@ -3,18 +3,32 @@
  *
  * @module
  */
-import { Maybe, NewTypeWithPhantom } from '@telostat/prelude';
+import { Maybe } 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 = string & {
+    readonly __tag: unique symbol;
+};
+/**
+ * Regular expression for currency codes in our concept.
  */
-export type CurrencyCode = NewTypeWithPhantom<'CurrencyCode', string>;
+export declare const REGEXP_CURRENCY_CODE: RegExp;
 /**
  * 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,
@@ -36,6 +50,8 @@ export declare function mkCurrencyCodeError(x: string): CurrencyCode;
 /**
  * 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.
  */

package/commons/-currency.js

@@ -5,20 +5,24 @@
  * @module
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unCurrencyCode = exports.mkCurrencyCodeError = exports.mkCurrencyCode = void 0;
+exports.unCurrencyCode = exports.mkCurrencyCodeError = exports.mkCurrencyCode = exports.REGEXP_CURRENCY_CODE = void 0;
 var prelude_1 = require("@telostat/prelude");
+/**
+ * Regular expression for currency codes in our concept.
+ */
+exports.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.
  */
 function mkCurrencyCode(x) {
-    return x !== x.trim() || x === '' ? prelude_1.Nothing : (0, prelude_1.Just)((0, prelude_1.mkPhantom)(x));
+    return exports.REGEXP_CURRENCY_CODE.test(x) ? (0, prelude_1.Just)(x) : prelude_1.Nothing;
 }
 exports.mkCurrencyCode = mkCurrencyCode;
 /**
@@ -34,17 +38,19 @@ exports.mkCurrencyCode = mkCurrencyCode;
  */
 function mkCurrencyCodeError(x) {
     return mkCurrencyCode(x).orDefaultLazy(function () {
-        throw new Error("Invalid currency code: \"".concat(x, "\""));
+        throw new Error("Invalid currency code: ".concat(x));
     });
 }
 exports.mkCurrencyCodeError = mkCurrencyCodeError;
 /**
  * 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.
  */
 function unCurrencyCode(x) {
-    return (0, prelude_1.unPhantom)(x);
+    return x;
 }
 exports.unCurrencyCode = unCurrencyCode;

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

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

package/commons/{-date-type.js → -datetype.js}

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dateTypes = void 0;
+exports.DATE_TYPES = void 0;
 /**
  * Translation table for DECAF FINREA action date types.
  */
-exports.dateTypes = [
+exports.DATE_TYPES = [
     { label: 'Trade Date', value: 'commitment' },
     { label: 'Value Date', value: 'settlement' },
 ];

package/commons/-id.d.ts

@@ -1,58 +1,150 @@
-import { NewTypeWithPhantom } from '@telostat/prelude';
 /**
- * Type definition for identifiers with value spaces discriminated over the
- * given phantom type.
+ * 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
  */
-export type Id<P, V> = NewTypeWithPhantom<P, V>;
+/**
+ * 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;
+export declare function mkDecafRecordId<T extends _DecafRecordIdFromNumber>(x: number): T;
+export declare function mkDecafRecordId<T extends _DecafRecordIdFromString>(x: string): T;
+export declare function unDecafRecordId<T extends _DecafRecordIdFromNumber>(x: T): number;
+export declare function unDecafRecordId<K extends _DecafRecordIdFromString>(x: K): string;
 /**
  * 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/commons/-id.js

@@ -1,2 +1,75 @@
 "use strict";
+/**
+ * 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
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.unDecafRecordId = exports.mkDecafRecordId = void 0;
+/**
+ * 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.
+ */
+function mkDecafRecordId(x) {
+    return x;
+}
+exports.mkDecafRecordId = mkDecafRecordId;
+/**
+ * Deconstructor for DECAF record identifiers.
+ *
+ * @param x DECAF record identifier.
+ * @returns Value of the DECAF record identifier (deduced from call-site usage).
+ */
+function unDecafRecordId(x) {
+    return x;
+}
+exports.unDecafRecordId = unDecafRecordId;

package/commons/index.d.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';

package/commons/index.js

@@ -10,10 +10,26 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.id = exports.datetype = exports.currency = void 0;
 __exportStar(require("./-currency"), exports);
-__exportStar(require("./-date-type"), exports);
+exports.currency = __importStar(require("./-currency"));
+__exportStar(require("./-datetype"), exports);
+exports.datetype = __importStar(require("./-datetype"));
 __exportStar(require("./-id"), exports);
+exports.id = __importStar(require("./-id"));

package/es/commons/-currency.d.ts

@@ -3,18 +3,32 @@
  *
  * @module
  */
-import { Maybe, NewTypeWithPhantom } from '@telostat/prelude';
+import { Maybe } 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 = string & {
+    readonly __tag: unique symbol;
+};
+/**
+ * Regular expression for currency codes in our concept.
  */
-export type CurrencyCode = NewTypeWithPhantom<'CurrencyCode', string>;
+export declare const REGEXP_CURRENCY_CODE: RegExp;
 /**
  * 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,
@@ -36,6 +50,8 @@ export declare function mkCurrencyCodeError(x: string): CurrencyCode;
 /**
  * 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.
  */

package/es/commons/-currency.js

@@ -3,19 +3,23 @@
  *
  * @module
  */
-import { Just, mkPhantom, Nothing, unPhantom } from '@telostat/prelude';
+import { Just, Nothing } from '@telostat/prelude';
+/**
+ * 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) {
-    return x !== x.trim() || x === '' ? Nothing : Just(mkPhantom(x));
+    return REGEXP_CURRENCY_CODE.test(x) ? Just(x) : Nothing;
 }
 /**
  * (Unsafely) attempts to create a {@link CurrencyCode} value with the given
@@ -30,15 +34,17 @@ export function mkCurrencyCode(x) {
  */
 export function mkCurrencyCodeError(x) {
     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) {
-    return unPhantom(x);
+    return x;
 }

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

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

package/es/commons/{-date-type.js → -datetype.js}

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