Merge branch 'main' into issue/45-cmcd-non-finite

Signed-off-by: Casey Occhialini <[email protected]>
streaming-video-technology-alliance · Nov 29, 2023 · a2b2364 · a2b2364
2 parents 897e5c5 + 469b97d
commit a2b2364
Show file tree

Hide file tree

Showing 115 changed files with 909 additions and 753 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,11 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+indent_style = tab
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,6 +18,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Add the ability to pass a base URL to all CMCD encode utilities to construct relative paths for `nor` [#50](https://github.com/streaming-video-technology-alliance/common-media-library/issues/50)
+
 ### Fixed
 - CMCD does not protect against non-Finite numeric values [#45](https://github.com/streaming-video-technology-alliance/common-media-library/issues/45)
 
@@ -157,7 +160,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.4.3]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.4.2...v0.4.3  
 [0.4.2]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.4.1...v0.4.2  
 [0.4.1]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.4.0...v0.4.1  
-[0.4.0]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.3.0...v0.4.0   
+[0.4.0]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.3.0...v0.4.0  
 [0.3.0]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.2.6...v0.3.0  
 [0.2.6]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.2.5...v0.2.6  
 [0.2.5]\: https://github.com/streaming-video-technology-alliance/common-media-library/compare/v0.2.4...v0.2.5  

diff --git a/dev/dev.js b/dev/dev.js
@@ -0,0 +1,3 @@
+import { appendCmcdQuery } from '@svta/common-media-library/cmcd/appendCmcdQuery.js';
+
+console.log(appendCmcdQuery('https://test.com/?CMCD=bs%2Cot%3Dm%2Csf%3Dh', { mtp: 123 }));
diff --git a/dev/index.html b/dev/index.html
@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+
+<body>
+  <script type="module" src="dev.js"></script>
+</body>
+
+</html>
diff --git a/dev/package.json b/dev/package.json
@@ -0,0 +1,22 @@
+{
+	"name": "@svta/common-media-library-dev",
+	"private": true,
+	"version": "0.5.1",
+	"license": "Apache-2.0",
+	"type": "module",
+	"homepage": "https://github.com/streaming-video-technology-alliance/common-media-library",
+	"authors": "Casey Occhialini <[email protected]>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/streaming-video-technology-alliance/common-media-library.git"
+	},
+	"bugs": {
+		"url": "https://github.com/streaming-video-technology-alliance/common-media-library/issues"
+	},
+	"scripts": {
+		"start": "web-dev-server --node-resolve --open --watch"
+	},
+	"devDependencies": {
+		"typedoc": "0.25.2"
+	}
+}
diff --git a/lib/config/common-media-library.api.md b/lib/config/common-media-library.api.md
@@ -50,9 +50,10 @@ export type CmcdCustomKey = CmCustomKey;
 
 // @beta
 export interface CmcdEncodeOptions {
+    baseUrl?: string;
     customHeaderMap?: CmcdHeadersMap;
     filter?: (key: CmcdKey) => boolean;
-    formatters?: Record<CmcdKey, (value: CmcdValue) => number | string>;
+    formatters?: Record<CmcdKey, CmcdFormatter>;
 }
 
 // @beta
@@ -63,10 +64,10 @@ export enum CmcdEncoding {
 }
 
 // @beta
-export type CmcdFormatter = (value: CmcdValue) => string;
+export type CmcdFormatter = (value: CmcdValue, options?: CmcdEncodeOptions) => string | number;
 
 // @beta
-export const CmcdFormatters: Record<string, (value: CmcdValue) => number | string | boolean>;
+export const CmcdFormatters: Record<string, CmcdFormatter>;
 
 // @beta
 export enum CmcdHeaderField {
@@ -350,6 +351,9 @@ export function toCmcdJson(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
 // @beta
 export function toCmcdQuery(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
 
+// @beta
+export function urlToRelativePath(url: string, base: string): string;
+
 // @beta
 export function utf8ArrayToStr(array: Uint8Array, exitOnNull?: boolean): string;
 

diff --git a/lib/src/cmcd.ts b/lib/src/cmcd.ts
@@ -1,6 +1,6 @@
 /**
  * A collection of tools for working with Common Media Client Data (CMCD).
- * 
+ *
  * @packageDocumentation
  */
 export { CMCD_PARAM } from './cmcd/CMCD_PARAM.js';

diff --git a/lib/src/cmcd/CMCD_PARAM.ts b/lib/src/cmcd/CMCD_PARAM.ts
@@ -1,8 +1,8 @@
 /**
  * CMCD parameter name.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export const CMCD_PARAM = 'CMCD';
diff --git a/lib/src/cmcd/Cmcd.ts b/lib/src/cmcd/Cmcd.ts
@@ -6,11 +6,11 @@ import { CmcdValue } from './CmcdValue.js';
 
 /**
  * Common Media Client Data (CMCD) is a standardized set of HTTP request header fields and query string parameters.
- * 
+ *
  * @see {@link https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf|CMCD Spec}
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export interface Cmcd {

diff --git a/lib/src/cmcd/CmcdCustomKey.ts b/lib/src/cmcd/CmcdCustomKey.ts
@@ -1,13 +1,13 @@
 import { CmCustomKey } from '../cta/CmCustomKey.js';
 
 /**
- * A custom key for CMCD. Custom keys MUST carry a hyphenated prefix 
- * to ensure that there will not be a namespace collision with future 
- * revisions to this specification. Clients SHOULD use a reverse-DNS 
+ * A custom key for CMCD. Custom keys MUST carry a hyphenated prefix
+ * to ensure that there will not be a namespace collision with future
+ * revisions to this specification. Clients SHOULD use a reverse-DNS
  * syntax when defining their own prefix.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export type CmcdCustomKey = CmCustomKey;
diff --git a/lib/src/cmcd/CmcdEncodeOptions.ts b/lib/src/cmcd/CmcdEncodeOptions.ts
@@ -1,31 +1,36 @@
+import { CmcdFormatter } from './CmcdFormatter.js';
 import { CmcdHeadersMap } from './CmcdHeadersMap.js';
 import { CmcdKey } from './CmcdKey.js';
-import { CmcdValue } from './CmcdValue.js';
 
 /**
  * Options for encoding CMCD values.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export interface CmcdEncodeOptions {
-  /**
-   * A map of CMCD keys to custom formatters.
-   */
-  formatters?: Record<CmcdKey, (value: CmcdValue) => number | string>;
+	/**
+	 * A map of CMCD keys to custom formatters.
+	 */
+	formatters?: Record<CmcdKey, CmcdFormatter>;
 
-  /**
-   * A map of CMCD header fields to custom CMCD keys.
-   */
-  customHeaderMap?: CmcdHeadersMap;
+	/**
+	 * A map of CMCD header fields to custom CMCD keys.
+	 */
+	customHeaderMap?: CmcdHeadersMap;
 
-  /**
-   * A filter function for CMCD keys.
-   * 
-   * @param key - The CMCD key to filter. 
-   * 
-   * @returns `true` if the key should be included, `false` otherwise.
-   */
-  filter?: (key: CmcdKey) => boolean;
+	/**
+	 * A filter function for CMCD keys.
+	 *
+	 * @param key - The CMCD key to filter.
+	 *
+	 * @returns `true` if the key should be included, `false` otherwise.
+	 */
+	filter?: (key: CmcdKey) => boolean;
+
+	/**
+	 * The base URL to use for relative URLs.
+	 */
+	baseUrl?: string;
 }
diff --git a/lib/src/cmcd/CmcdEncoding.ts b/lib/src/cmcd/CmcdEncoding.ts
@@ -1,23 +1,23 @@
 /**
  * CMCD encoding types.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export enum CmcdEncoding {
-  /**
-   * JSON
-   */
-  JSON = 'json',
+	/**
+	 * JSON
+	 */
+	JSON = 'json',
 
-  /**
-   * Query string
-   */
-  QUERY = 'query',
+	/**
+	 * Query string
+	 */
+	QUERY = 'query',
 
-  /**
-   * Request headers
-   */
-  HEADERS = 'headers',
+	/**
+	 * Request headers
+	 */
+	HEADERS = 'headers',
 }
diff --git a/lib/src/cmcd/CmcdFormatter.ts b/lib/src/cmcd/CmcdFormatter.ts
@@ -1,14 +1,15 @@
+import { CmcdEncodeOptions } from './CmcdEncodeOptions.js';
 import { CmcdValue } from './CmcdValue.js';
 
 /**
  * A formatter for CMCD values.
- * 
+ *
  * @param value - The value to format.
- * 
+ *
  * @returns The formatted value.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
-export type CmcdFormatter = (value: CmcdValue) => string;
+export type CmcdFormatter = (value: CmcdValue, options?: CmcdEncodeOptions) => string | number;
diff --git a/lib/src/cmcd/CmcdFormatters.ts b/lib/src/cmcd/CmcdFormatters.ts
@@ -1,17 +1,25 @@
+import { urlToRelativePath } from '../utils.js';
+import { CmcdEncodeOptions } from './CmcdEncodeOptions.js';
+import { CmcdFormatter } from './CmcdFormatter.js';
 import { CmcdValue } from './CmcdValue.js';
 
 const toRounded = (value: CmcdValue) => Math.round(value as number);
-const toUrlSafe = (value: CmcdValue) => encodeURIComponent(value as string);
+const toUrlSafe = (value: CmcdValue, options?: CmcdEncodeOptions) => {
+	if (options?.baseUrl) {
+		value = urlToRelativePath(value as string, options.baseUrl);
+	}
+	return encodeURIComponent(value as string);
+};
 const toHundred = (value: CmcdValue) => toRounded(value as number / 100) * 100;
 
 /**
  * The default formatters for CMCD values.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
-export const CmcdFormatters: Record<string, (value: CmcdValue) => number | string | boolean> = {
+export const CmcdFormatters: Record<string, CmcdFormatter> = {
 	/**
 	 * Bitrate (kbps) rounded integer
 	 */

diff --git a/lib/src/cmcd/CmcdHeaderField.ts b/lib/src/cmcd/CmcdHeaderField.ts
@@ -1,8 +1,8 @@
 /**
  * CMCD header fields.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export enum CmcdHeaderField {

diff --git a/lib/src/cmcd/CmcdHeaderMap.ts b/lib/src/cmcd/CmcdHeaderMap.ts
@@ -3,9 +3,9 @@ import { CmcdHeadersMap } from './CmcdHeadersMap.js';
 
 /**
  * The map of CMCD header fields to official CMCD keys.
- * 
+ *
  * @internal
- * 
+ *
  * @group CMCD
  */
 export const CmcdHeaderMap: CmcdHeadersMap = {

diff --git a/lib/src/cmcd/CmcdHeadersMap.ts b/lib/src/cmcd/CmcdHeadersMap.ts
@@ -3,9 +3,9 @@ import { CmcdKey } from './CmcdKey.js';
 
 /**
  * A map of CMCD header fields to CMCD keys.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export type CmcdHeadersMap = Record<CmcdHeaderField, CmcdKey[]>;
diff --git a/lib/src/cmcd/CmcdKey.ts b/lib/src/cmcd/CmcdKey.ts
@@ -2,9 +2,9 @@ import { Cmcd } from './Cmcd.js';
 
 /**
  * A CMCD key.
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export type CmcdKey = keyof Cmcd;
diff --git a/lib/src/cmcd/CmcdObjectType.ts b/lib/src/cmcd/CmcdObjectType.ts
@@ -1,8 +1,8 @@
 /**
  * Common Media Object Type
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export { CmObjectType as CmcdObjectType } from '../cta/CmObjectType.js';
diff --git a/lib/src/cmcd/CmcdStreamType.ts b/lib/src/cmcd/CmcdStreamType.ts
@@ -1,8 +1,8 @@
 /**
  * Common Media Streaming Type
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export { CmStreamType as CmcdStreamType } from '../cta/CmStreamType.js';
diff --git a/lib/src/cmcd/CmcdStreamingFormat.ts b/lib/src/cmcd/CmcdStreamingFormat.ts
@@ -1,8 +1,8 @@
 /**
  * Common Media Streaming Format
- * 
+ *
  * @group CMCD
- * 
+ *
  * @beta
  */
 export { CmStreamingFormat as CmcdStreamingFormat } from '../cta/CmStreamingFormat.js';
diff --git a/lib/src/cmcd/CmcdValue.ts b/lib/src/cmcd/CmcdValue.ts
@@ -4,7 +4,7 @@ import { CmValue } from '../cta/CmValue.js';
  * CMCD Value
  *
  * @group CMCD
- *  
+ *
  * @beta
  */
 export type CmcdValue = CmValue;
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		import { appendCmcdQuery } from '@svta/common-media-library/cmcd/appendCmcdQuery.js';

		console.log(appendCmcdQuery('https://test.com/?CMCD=bs%2Cot%3Dm%2Csf%3Dh', { mtp: 123 }));