BADGERS-307 feat(debugger): Record changes to metric values over time (…

…#324)

* Linting on ReadyHelper

* What doesn't this change

* Remove Terser - Unused

* it aint much

* but it's darn honest work

* wip: add media element types

* Combine Message and Metric Types

* [WIP] Classify Chronicle

* Fix Chronicle Unit Tests

* Fix all tests

* chore: change chronicle to TypeScript

* wip: type bonanza

* wip: metric interface

* Type that extracts Metric Value based on key

* Fix Types for Metric Get

* wip: use new api

* WIP Message Push Functions

* Remove API Call and Event from Trace

* Export EntryForIdentifier, instead of Message/MetricForKey/Level

* wip: elmo burn emoji

* getLatestMetric

* refine types

* chore: disable prefer-at

* feat: chronicle is amazing now

* DebugPresenter => DebugFormatter

* Minor linting changes

* feat: add event trace

* chore: make debugtool TypeScript

* chore: make debugformatter TypeScript

* wip: im bad at splitting commits

* feat: statechange trace

* feat: use new chronicle

* fix: all the debugger tests

* chore: check for unused locals

* Remove redundant test

* refactor: restructure tests

* test(debugger): chronicle records an error trace

* feat(debugger): chronicle records an error trace

* test(debugger): expect error records to be traces

* test(debugger): debugtool tests expect error to be a trace

* feat(debugger): debugview renders error traces

* feat(debugger): show a subset of events to the view

* refactor(debugger): call trace to record a trace in the chronicle

* refactor(debugger): initialise a new view controller on teardown

* feat: track session start and end times

* test: same-value metrics don't update over time

* Fix various compiler errors

* Add buffered-audio metric

* Fix Debug View Test

* Don't record duplicated values

* chore: rename pushMetric to appendMetric

* rework internal data structure

* test(debugger): fix remaining tests

* refactor: clean up

* feat: don't store history for buffer length and seekable range

* feat: warn if metrics get many

* chore: make more metrics static

* chore: as cast

* feat: log gap jumps to the debugger

* chore: give types to mediakinds

* fix: type error

* chore: declaration files

* chore: mark dashjs external

* chore: build dist on install

* fix: avoid Object values

* fix: bitrate

* Add the skeleton Compressor

* Export Chronicle and Debug Tool on Main API

* Export Default in Compressor

* Don't compile tests with Typescript for Prod

* Add Declaration Compile

* Better Declaration Build

* Typescriptify random stuff, start adding GZip

* Actually commit new files

* Low Hanging Fruit Typescriptify

* Save TransferFormats before committing

* Todo Tests

* Remove FFlate

* feat: create union type

* wip: dist output?

* fix: use if instead of booleans

* fix: add back -f flag

* Render to debugview on interval rather than on every update

* wip: try rollup-plugin-dts

* clean up

* chore: remove commented out lines

* Update Package Lock

* `as const`

* Don't export Chronicle on BSP API

* Don't re-export `compress` and `decompess`

* Change DebugView back into a singleton

* Make frames-dropped a static metric

* Remove redundant code for initially setting debug-view render interval

* Typescriptify Resizer

* Make Compressor Committable

* Named Exports in ./model, and Typescriptify ReadyHelper

* Linting

* Call showView() in DebugViewController tests to start render interval

* Zod Skeleton

* More work on Zod Schema - Message

* feat: log buffered ranges on waiting/stall event

* TraceKinds and MetricKeys Zod

* \'Compression\' is `JSON.stringify` for now

* Merge "Validation" Branch into "Compression" Branch (#321)

* Typescriptify most of Utils

* Remove Validator

* Export Types from Chronicle on TS Interface

* Export Chronicle Enums etc.

* feat: display all entries in the view when log-level is debug

* fix: generate working types

* fix: dev build

* fix: replace all hyphens

* Change tail to 100

* Kebab Case

* No JSON Stringify in Compressor

* Remove Compressor

* chore: sort traces first

* refactor: use kind as identifier for all categories

* fix: report correct media type with quality change

* chore: undo whitespace changes

* chore: undo whitespace changes

* feat: record buffers on playing event

* style: rename wrung to inverted

* chore: make chronicle warn -> error

* feat: make init data a type

* docs: clean up type

* docs: update Chronicle docs

---------

Co-authored-by: James Bungay <[email protected]>
Co-authored-by: ShiningTrapez <[email protected]>

.eslintrc.yaml

@@ -5,7 +5,7 @@ env:
   es6: true
   node: true
 
-parser: "@babel/eslint-parser"
+parser: "@typescript-eslint/parser"
 
 parserOptions:
   ecmaVersion: 2015
@@ -18,16 +18,16 @@ ignorePatterns:
 
 extends:
   - eslint:recommended
-  - plugin:import/recommended
+  - plugin:@typescript-eslint/recommended
   - plugin:json/recommended
   - plugin:sonarjs/recommended
   - plugin:unicorn/recommended
 
 plugins:
-  - import
   - json
   - sonarjs
   - unicorn
+  - "@typescript-eslint"
 
 rules:
   # Discuss these!
@@ -60,8 +60,8 @@ rules:
   prefer-spread: error
   quote-props: [error, as-needed]
   yoda: [error, never]
-  import/prefer-default-export: error
   unicorn/no-null: off
+  unicorn/switch-case-braces: [error, avoid]
 
   spaced-comment:
     - error
@@ -111,22 +111,13 @@ rules:
   no-unneeded-ternary: error
   no-unreachable-loop: error
   no-unused-private-class-members: error
-  no-unused-vars: [error, { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }]
   no-useless-call: error
   no-useless-constructor: error
   no-useless-return: error
   no-use-before-define: [error, nofunc]
   no-with: error
   use-isnan: error
   wrap-iife: [error, any]
-  import/first: error
-  import/no-mutable-exports: error
-
-  import/no-unused-modules:
-    - error
-    - unusedExports: true
-      ignoreExports:
-        - "src/main.js"
 
   # TV compatibility
   no-prototype-builtins: off
@@ -136,16 +127,24 @@ rules:
   unicorn/no-array-method-this-argument: off
   unicorn/no-for-loop: off
   unicorn/numeric-separators-style: off
+  unicorn/prefer-at: off
   unicorn/prefer-array-flat: off
   unicorn/prefer-includes: off
   unicorn/prefer-dom-node-append: off
   unicorn/prefer-number-properties: off
   unicorn/prefer-math-trunc: off
+  unicorn/prefer-optional-catch-binding: off
+  unicorn/prefer-string-replace-all: off
+  unicorn/prefer-dom-node-remove: off
+
+  # Typescript
+  "@typescript-eslint/no-unused-vars": [error, { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }]
+  "@typescript-eslint/no-explicit-any": warn
 
 overrides:
   # General test overrides
   - files:
-      - "**/*.test.{js,mjs}"
+      - "**/*.test.{js,mjs,ts}"
     rules:
       max-nested-callbacks: off
       sonarjs/no-duplicate-string: off

babel.config.json

@@ -1,3 +1,3 @@
 {
-  "presets": [["@babel/preset-env"]]
+  "presets": [["@babel/preset-env"], ["@babel/preset-typescript"]]
 }

docs/tutorials/02-settings-and-overrides.md

@@ -39,7 +39,7 @@ type failoverResetTime = number is FiniteNumber
 Provide a sorting algorithm to reorder the available media sources after a failover.
 
 ```ts
-type failoverSort = (...sources: [...string]) => [...string]
+type failoverSort = (sources: string[]) => string[]
 ```
 
 ### `streaming.seekDurationPadding`

docs/tutorials/Debugging.md

@@ -1,11 +1,25 @@
-During development, `bigscreen-player` offers a form of debugging with an on-screen debugger. Using this tool, specific events can be monitored to check successful execution of the program logic. This is particularly useful where no native JS consoles are accessible on certain devices.
+BigscreenPlayer offers logging through "Chronicle", our own debugging solution. This tool can be used to monitor specific events and changes in metrics over time in order to validate execution of the program logic.
+
+## On-Screen Debugging
+
+We offer an on-screen debugger as part of our solution. This is particularly useful where no native JavaScript consoles are natively accessible on devices.
 
 The on-screen debugger can be shown using:
-```
+
+```js
 bigscreenPlayer.toggleDebug()
 ```
 
-### The Chronicle
-The debug-tool latches on top of the `chronicle` which acts similarly to the plugin interface. It has a reference to all of the callbacks that need to be updated upon a debug event occurring. 
+### Structured Logging
+
+Logs in the Chronicle are _structured_. What is more, logs are captured even when the on-screen debugger isn't active. You can access the complete record of the playback session using:
+
+```js
+bigscreenPlayer.getDebugLogs()
+```
+
+You can find the full structure of the data returned by this function in the source file `chronicle.ts`. In short, `getDebugLogs` returns the Chronicle record as a flat array of entries. Each entry falls into one of three (3) categories:
 
-This could allow for a possible extension of the debugging interface *if* needed.
+1. Message: Unstructured string data. Think `console` output.
+2. Metrics: Values that change over time, such as dropped frames.
+3. Traces: Snapshots and one-of data, such as errors and events.

docs/tutorials/tutorials.json

@@ -11,6 +11,9 @@
   "cdn-failover": {
     "title": "CDN Failover"
   },
+  "debugging": {
+    "title": "Debugging"
+  },
   "live-streaming": {
     "title": "Live"
   }

index.html

@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html>
     <head>
         <meta charset="utf-8" />

jest.config.ts

@@ -0,0 +1,12 @@
+import type { Config } from "jest"
+
+const config: Config = {
+  testEnvironment: "jsdom",
+  showSeed: true,
+  transform: {
+    "\\.[j]sx?$": "babel-jest",
+    "\\.[t]sx?$": "ts-jest",
+  },
+}
+
+export default config

jsdoc.conf.json

@@ -5,11 +5,11 @@
   },
   "source": {
     "include": ["src"],
-    "includePattern": ".js$",
+    "includePattern": ".(js|ts)$",
     "excludePattern": "(node_modules/|docs)"
   },
   "sourceType": "module",
-  "plugins": ["plugins/markdown"],
+  "plugins": ["plugins/markdown", "node_modules/better-docs/typescript"],
   "templates": {
     "cleverLinks": false,
     "monospaceLinks": true,