1 | # NodeJS / TypeScript Readium-2 "utils"
|
2 |
|
3 | NodeJS implementation (written in TypeScript) of utilities for the Readium2 architecture ( https://github.com/readium/architecture/ ).
|
4 |
|
5 | [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](/LICENSE)
|
6 |
|
7 | ## Build status
|
8 |
|
9 | [![NPM](https://img.shields.io/npm/v/r2-utils-js.svg)](https://www.npmjs.com/package/r2-utils-js) [![David](https://david-dm.org/readium/r2-utils-js/status.svg)](https://david-dm.org/readium/r2-utils-js)
|
10 |
|
11 | [Changelog](/CHANGELOG.md)
|
12 |
|
13 | ## Prerequisites
|
14 |
|
15 | 1) https://nodejs.org NodeJS >= 8, NPM >= 5 (check with command line `node --version` and `npm --version`)
|
16 | 2) OPTIONAL: https://yarnpkg.com Yarn >= 1.0 (check with command line `yarn --version`)
|
17 |
|
18 | ## GitHub repository
|
19 |
|
20 | https://github.com/readium/r2-utils-js
|
21 |
|
22 | There is no [github.io](https://readium.github.io/r2-utils-js) site for this project (no [gh-pages](https://github.com/readium/r2-utils-js/tree/gh-pages) branch).
|
23 |
|
24 | ## NPM package
|
25 |
|
26 | https://www.npmjs.com/package/r2-utils-js
|
27 |
|
28 | Command line install:
|
29 |
|
30 | `npm install r2-utils-js`
|
31 | OR
|
32 | `yarn add r2-utils-js`
|
33 |
|
34 | ...or manually add in your `package.json`:
|
35 | ```json
|
36 | "dependencies": {
|
37 | "r2-utils-js": "latest"
|
38 | }
|
39 | ```
|
40 |
|
41 | The JavaScript code distributed in the NPM package is usable as-is (no transpilation required), as it is automatically-generated from the TypeScript source.
|
42 |
|
43 | Several ECMAScript flavours are provided out-of-the-box: ES5, ES6-2015, ES7-2016, ES8-2017:
|
44 |
|
45 | https://unpkg.com/r2-utils-js/dist/
|
46 |
|
47 | (alternatively, GitHub mirror with semantic-versioning release tags: https://github.com/edrlab/r2-utils-js-dist/tree/develop/dist/ )
|
48 |
|
49 | The JavaScript code is not bundled, and it uses `require()` statement for imports (NodeJS style).
|
50 |
|
51 | More information about NodeJS compatibility:
|
52 |
|
53 | http://node.green
|
54 |
|
55 | Note that web-browser Javascript is currently not supported (only NodeJS runtimes).
|
56 |
|
57 | The type definitions (aka "typings") are included as `*.d.ts` files in `./node_modules/r2-utils-js/dist/**`, so this package can be used directly in a TypeScript project.
|
58 |
|
59 | Example usage:
|
60 |
|
61 | ```javascript
|
62 | // currently no index file
|
63 | // import { * } from "r2-utils-js";
|
64 |
|
65 | // ES5 import (assuming node_modules/r2-utils-js/):
|
66 | import { sortObject } from "r2-utils-js/dist/es5/src/_utils/JsonUtils";
|
67 |
|
68 | // ... or alternatively using a convenient path alias in the TypeScript config (+ WebPack etc.):
|
69 | import { sortObject } from "@r2-utils-js/JsonUtils";
|
70 | ```
|
71 |
|
72 | ## Dependencies
|
73 |
|
74 | https://david-dm.org/readium/r2-utils-js
|
75 |
|
76 | A [package-lock.json](https://github.com/readium/r2-utils-js/blob/develop/package-lock.json) is provided (modern NPM replacement for `npm-shrinkwrap.json`).
|
77 |
|
78 | A [yarn.lock](https://github.com/readium/r2-utils-js/blob/develop/yarn.lock) file is currently *not* provided at the root of the source tree.
|
79 |
|
80 | ## Continuous Integration
|
81 |
|
82 | TODO (unit tests?)
|
83 | https://travis-ci.org/readium/r2-utils-js
|
84 |
|
85 | Badge: `[![Travis](https://travis-ci.org/readium/r2-utils-js.svg?branch=develop)](https://travis-ci.org/readium/r2-utils-js)`
|
86 |
|
87 | ## Version(s), Git revision(s)
|
88 |
|
89 | NPM package (latest published):
|
90 |
|
91 | https://unpkg.com/r2-utils-js/dist/gitrev.json
|
92 |
|
93 | Alternatively, GitHub mirror with semantic-versioning release tags:
|
94 |
|
95 | https://raw.githack.com/edrlab/r2-utils-js-dist/develop/dist/gitrev.json
|
96 |
|
97 | ## Developer quick start
|
98 |
|
99 | Command line steps (NPM, but similar with YARN):
|
100 |
|
101 | 1) `cd r2-utils-js`
|
102 | 2) `git status` (please ensure there are no local changes, especially in `package-lock.json` and the dependency versions in `package.json`)
|
103 | 3) `rm -rf node_modules` (to start from a clean slate)
|
104 | 4) `npm install`, or alternatively `npm ci` (both commands initialize the `node_modules` tree of package dependencies, based on the strict `package-lock.json` definition)
|
105 | 5) `npm run build:all` (invoke the main build script: clean, lint, compile)
|
106 | 6) `ls dist` (that's the build output which gets published as NPM package)
|
107 |
|
108 | ## Documentation
|
109 |
|
110 | TODO
|