imscJS 2.0-dev.1

.github/workflows/ci.pr.yml

@@ -0,0 +1,32 @@
+name: Pull Request CI
+
+on:
+  pull_request:
+
+jobs:
+  pull_request_ci:
+    concurrency:
+      group: ${{ github.ref }}
+      cancel-in-progress: true
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test

Gruntfile.cjs

@@ -0,0 +1,82 @@
+module.exports = function (grunt) {
+
+    grunt.initConfig({
+
+        properties: grunt.file.readJSON("properties.json"),
+
+        pkg: grunt.file.readJSON("package.json"),
+
+        clean: ["<%= properties.webappBuildDir %>", "<%= properties.umdBuildDir %>"],
+
+        sync: {
+            all: {
+                files:
+                    [
+                        // copy tests
+                        { expand: true, cwd: "<%= properties.webappTestDir %>", src: "**", dest: "<%= properties.webappBuildDir %>" },
+
+                        // copy tests resources
+                        { expand: true, cwd: "<%= properties.unitTestsResourcesDir %>", src: "imsc-tests/imsc1/ttml/**", dest: "<%= properties.webappBuildDir %>" },
+                        { expand: true, cwd: "<%= properties.unitTestsResourcesDir %>", src: "imsc-tests/imsc1/tests.json", dest: "<%= properties.webappBuildDir %>" },
+                        { expand: true, cwd: "<%= properties.unitTestsResourcesDir %>", src: "imsc-tests/imsc1_1/ttml/**", dest: "<%= properties.webappBuildDir %>" },
+                        { expand: true, cwd: "<%= properties.unitTestsResourcesDir %>", src: "imsc-tests/imsc1_1/tests.json", dest: "<%= properties.webappBuildDir %>" },
+                        { expand: true, cwd: "<%= properties.unitTestsResourcesDir %>", src: "unit-tests/**", dest: "<%= properties.webappBuildDir %>" },
+                    ],
+            },
+
+            release: {
+                src: "<%= properties.umdBuildDir %>/<%= properties.umdMinName %>",
+                dest: "<%= properties.webappBuildDir %>/libs/imsc.js",
+            },
+
+            debug: {
+                src: "<%= properties.umdBuildDir %>/<%= properties.umdDebugName %>",
+                dest: "<%= properties.webappBuildDir %>/libs/imsc.js",
+            },
+        },
+
+        npmcopy: {
+            default: {
+                files: {
+                    "<%= properties.webappBuildDir %>/libs/": [
+                        "filesaver.js-npm:main",
+                        "jszip/dist/jszip.js",
+                    ],
+                },
+            },
+        },
+
+        exec: {
+            compile: {
+                cmd: "npx tsc",
+            },
+
+            lint: {
+                cmd: "npx eslint .",
+            },
+
+            bundle: {
+                cmd: "npx rollup -c rollup.config.js",
+            },
+        },
+    },
+
+    );
+
+    grunt.loadNpmTasks("grunt-contrib-clean");
+
+    grunt.loadNpmTasks("grunt-npmcopy");
+
+    grunt.loadNpmTasks("grunt-sync");
+
+    grunt.loadNpmTasks("grunt-exec");
+
+    grunt.registerTask("lint", ["exec:lint"]);
+
+    grunt.registerTask("build:release", ["lint", "exec:compile", "exec:bundle", "sync:all", "sync:release", "npmcopy"]);
+
+    grunt.registerTask("build:debug", ["lint", "exec:compile", "exec:bundle", "sync:all", "sync:debug", "npmcopy"]);
+
+    grunt.registerTask("build", ["build:debug"]);
+
+};

README.md

@@ -32,7 +32,7 @@ imscJS bugs are tracked at https://github.com/sandflow/imscJS/issues.
 RUNTIME DEPENDENCIES
 ====================
 
-(required) [sax-js 1.2.1](https://www.npmjs.com/package/sax)
+imscJS requires an XML parser. By default it uses the browser's native [`DOMParser`](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser), so no additional library is needed in a browser environment. In environments where `DOMParser` is not available, e.g. Node.js, the caller must provide `fromXML()` with a parser that implements the contract defined in [src/main/js/parser.js](src/main/js/parser.js), e.g. [sax-js](https://www.npmjs.com/package/sax).
 
 Rendering to HTML5 requires a browser environment, but parsing an IMSC document and transforming it into ISDs does not.
 
@@ -50,12 +50,11 @@ DEVELOPMENT DEPENDENCIES
 QUICK START
 ===========
 
-* run the `build` target defined in [Gruntfile.js](Gruntfile.js) using [grunt](http://gruntjs.com/).
+* run the `build` target defined in [Gruntfile.cjs](./Gruntfile.cjs) using [grunt](http://gruntjs.com/).
 
-* the resulting `imsc.js` and `sax.js` files at `build/public_html/libs` are, respectively, the imscJS library and its sax-js dependency. For example, both libraries can be included in a web page as follows:
+* the resulting `imsc.js` file at `build/public_html/libs` is the imscJS library. For example, it can be included in a web page as follows:
 
 ```html
-    <script src="libs/sax.js"></script>
     <script src="libs/imsc.js"></script>
 ```
 
@@ -71,7 +70,7 @@ API
 
 imscJS renders an IMSC document in three distinct steps:
 
-* `fromXML(xmlstring, errorHandler, metadataHandler)` parses the document and returns a TT object. The latter contains opaque representation of the document and exposes the method `getMediaTimeEvents()` that returns a list of time offsets (in seconds) of the ISD, i.e. the points in time where the visual representation of the document change.
+* `fromXML(xmlstring, errorHandler, metadataHandler, parser)` parses the document and returns a TT object. The latter contains opaque representation of the document and exposes the method `getMediaTimeEvents()` that returns a list of time offsets (in seconds) of the ISD, i.e. the points in time where the visual representation of the document change. The optional `parser` argument allows the caller to provide an alternative XML parser, e.g. in environments where the browser's native `DOMParser` is not available.
 
 * `generateISD(tt, offset, errorHandler)` creates a canonical representation of the document (provided as a TT object generated by `fromXML()`) at a point in time (`offset` parameter). This point in time does not have to be one of the values returned by `getMediaTimeEvents()`. For example, given an ISOBMFF sample covering the interval `[a, b[`, `generateISD(tt, offset, errorHandler)` would be called first with `offset = a`, then in turn with offset set to each value of `getMediaTimeEvents()` that fall in the interval `]a, b[`.
 
@@ -104,12 +103,11 @@ BUILD
 imscJS is built using the `build:release` or `build:debug` Grunt tasks -- the `build` task is an alias of `build:debug`.
 
 The `dist` directory contains the following build artifacts:
-* `imsc.all.debug.js`: Non-minified build that includes the sax-js dependency.
-* `imsc.all.min.js`: Minified build that includes the sax-js dependency.
-* `imsc.debug.js`: Non-minified build that does not include the sax-js dependency.
-* `imsc.min.js`: Minified build that does not include the sax-js dependency.
+* `imsc.debug.js`: Non-minified UMD build.
+* `imsc.min.js`: Minified UMD build.
+* `main/`: ES modules and TypeScript type declarations, used when the library is imported as an NPM package.
 
-The `build/public_html/libs/imsc.js` files is identical to:
+The `build/public_html/libs/imsc.js` file is identical to:
 * `imsc.debug.js`, if the `build:debug` task is executed.
 * `imsc.min.js`, if the `build:release` task is executed.
 
@@ -150,7 +148,7 @@ NOTABLE DIRECTORIES AND FILES
 
 * [package.json](package.json): NPM package definition
 
-* [Gruntfile.js](Gruntfile.js): Grunt build script
+* [Gruntfile.cjs](Gruntfile.cjs): Grunt build script
 
 * [properties.json](properties.json): General project properties
 

eslint.config.js

@@ -0,0 +1,31 @@
+import js from "@eslint/js";
+import globals from "globals";
+
+export default [
+  {
+    ignores: [
+      "src/test/webapp/**/*",
+      "dist",
+      "build",
+    ],
+  },
+  js.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        QUnit: true,
+        tests: true,
+      },
+    },
+    rules: {
+      "no-var": "error",
+      "prefer-const": "error",
+      "quotes": ["error", "double", { "avoidEscape": true, "allowTemplateLiterals": true }],
+      "no-trailing-spaces": "error",
+      "no-multiple-empty-lines": ["error", { "max": 1 }],
+      "comma-dangle": ["error", "always-multiline"],
+      "eol-last": ["error", "always"],
+    },
+  },
+];