From 422d84e447fc080ef5e401be53d55a65b86a6edd Mon Sep 17 00:00:00 2001 From: ironkayman Date: Sun, 7 Aug 2022 23:30:56 +0300 Subject: [PATCH 1/6] :memo: README: update available import module types [ci skip] --- README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 93 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 469e8f92..38299b36 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -### TKO (“Technical Knockout”) +# TKO (“Technical Knockout”) [![npm version](https://badge.fury.io/js/tko.svg)](https://badge.fury.io/js/tko) [![Join the chat at https://gitter.im/knockout/tko](https://badges.gitter.im/knockout/tko.svg)](https://gitter.im/knockout/tko?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) @@ -11,29 +11,108 @@ -**TKO** houses the monorepo of [Knockout](https://github.com/knockout/knockout). +1. [Intro](#intro) +2. [Getting Started](#getting-started) + 1. [Download](#download) + 1. [Reference](#download-reference) + 2. [Compatibility build](#download-compatibility) + 3. [Over CDN](#download-cdn) + 2. [Usage / import](#usage) + 1. [ESM](#imports-esm) + 2. [IIFE](#imports-iife) + 3. [CommonJS](#imports-cjs) + 4. [MJS](#imports-mjs) + 3. [Sites](#sites) +3. [Using the Monporepo](#monorepo) +4. [Objectives](#objectives) +5. [Roadmap](#roadmap) +6. [License](#license) +7. [Shoutouts](#shoutouts) -### Getting Started +
+## Getting Started +--- + + + +**TKO** serves as a foundation for `Knockout 4` which goal is to become a drop-in replacement and a feature-rich expansion of already existing KnockoutJS (3+) while adhearing new standarts and paradigms of web developmentent. Its built on top of current KnockoutJS featurelist while being [mostly compatible](https://www.tko.io/3to4) with it, further about it and build differences at [download](#download) section. + + +### Download To install use one of the usual package managers e.g. +#### Reference build: - $ `yarn add @tko/build.reference` - $ `npm install @tko/build.reference` +This is the canonical build without compatibilities with older KnockoutJS versions + +#### Compabibility build: +- $ `yarn add @tko/build.knockout` +- $ `npm install @tko/build.knockout` +This Knockout build has some backwards compatibility that is not in the reference build. See the build differences, here: https://tko.io/3to4 + +#### Over CDN +> **Note**: Latest version available is `alpha8` + +- *Reference* Build: https://cdn.jsdelivr.net/npm/@tko/build.reference@4.0.0-alpha8/dist/build.reference.min.js +- *Compatibility* Build: https://cdn.jsdelivr.net/npm/@tko/build.knockout@4.0.0-alpha8/dist/build.knockout.min.js + + +
+ +### Using TKO in a project +Currently there is no default package root import due to availability of different builds listed below. Every TKO build supports all listed below module types: + +* ESM + + ```js + import ko from "@tko/build.reference/dist/index.js" + ``` + + `ko` is default export so feel free to change import name on your desired. + +* IIFE + + ```js + import "@tko/build.reference/dist/browser.js" + // or use already minified bundle + import "@tko/build.reference/dist/browser.min.js" + ``` + + Imported namespace is available *only* as `tko`. + +* CommonJS + + ```js + "@tko/build.reference/dist/index.cjs" + ``` + + TODO + +* MJS + + ```js + "@tko/build.reference/dist/index.mjs" + ``` + + TODO -Over CDN +> Note: you can check imported TKO version by looking at its namespace attribute `.version` in runtime. -- Reference Build: https://cdn.jsdelivr.net/npm/@tko/build.reference@4.0.0-alpha8/dist/build.reference.min.js -#### Knockout Build -The Knockout build has some backwards compatibility that is not in the reference build. See the build differences, here: https://tko.io/3to4 +### Sites -It's available as `@tko/build.knockout`, and over CDN: +Currently there are 2 points of interest which further would be considered a wiki: +- https://tko.io - wiki specifically for TKO (*not Knockout 4*) +- https://brianmhunt.github.io/knockout - Work In Profress wiki/docs for Knockout -- Knockout Build https://cdn.jsdelivr.net/npm/@tko/build.knockout@4.0.0-alpha8/dist/build.knockout.min.js +
-### Using the Monorepo +## Using the Monorepo +--- | Command | Effect | | ------- | ------ | @@ -72,7 +151,7 @@ test; requires that Sauce Connect be already running. Note that running `karma` or `rollup` will create a `visual.html` file that shows the proportional size of imports into each package. -### Objectives +## Objectives TKO aims to become a base for future versions of Knockout. The objectives include: @@ -89,16 +168,16 @@ TKO aims to become a base for future versions of Knockout. The objectives inclu - Quality plugins have lots of boilerplate for compilation, release, documentation, and testing -## Next steps +## Roadmap / Next steps There's an [issue for that](https://github.com/knockout/tko/issues/1). -## License +## License MIT license - [http://www.opensource.org/licenses/mit-license.php.](http://www.opensource.org/licenses/mit-license.php) -## Shout Outs +## Shout Outs
From f6cbcda30bdcf0a2afe8eee1bc417f2a008ee660 Mon Sep 17 00:00:00 2001 From: ironkayman Date: Mon, 8 Aug 2022 00:01:48 +0300 Subject: [PATCH 2/6] :memo: README: update most commonly used commands list [ci skip] --- README.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 38299b36..c042e0a3 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ Currently there is no default package root import due to availability of differe TODO -> Note: you can check imported TKO version by looking at its namespace attribute `.version` in runtime. +> **Note**: you can check imported TKO version by looking at its namespace attribute `.version` in runtime. ### Sites @@ -114,17 +114,23 @@ Currently there are 2 points of interest which further would be considered a wik ## Using the Monorepo --- +The default package manager for monorepo currently is `npm` with the addition of [Lerna](https://lerna.js.org/docs/getting-started) as a viable choice for monorepo management. + +First thing at getting familiar with the project monorepo is to look at `Makefile` at project root. Since its a separate file spanning entire repo, we will cover only the most used commands: + | Command | Effect | | ------- | ------ | | $ `git clone git@github.com:knockout/tko` | Clone the repository. -| $ `npm install -g yarn` otherwise | Ensure yarn is globally available -| $ `yarn` | Install local node packages and link tko modules -| $ `yarn test` | Run all tests. See below. -| $ `yarn watch` | Run all tests and watch for changes. See below. -| $ `yarn build` | Build tko\[.module\]\[.es6\]\[.min\].js files, where `.es6` version has not been transpiled -| $ `lerna publish` | Bump versions and publish to npm registry - -Checkout `package.json => scripts` for more commands that can be executed with `yarn {command}`. +| $ `make` | Install all dependencies, build reference and compatibility versions of TKO at `builds/*/dist/*` (without any transpilation - needs proving). It is the `default` behavior, calling `all` directive. +| $ `make clean` | empties build directories `.../dist/*` and `package-lock.json`'s inside of every `package/*` and `builds/*` +| $ `npm i` | Install local node packages and link tko modules +| $ `make test` | Run all tests. See below. +| $ `make watch` | Run all tests and watch for changes. See below. +| $ `make publish-unpublished` | Bump versions and publish to npm registry + + +--- +> **TODO**: remove rollup info as current version uses ESbuild In each individual `packages/*/` directory, you can also run (presuming `rollup` and `karma` are installed globally): From 796afd72669208c21a3db550c22918215a792f24 Mon Sep 17 00:00:00 2001 From: ironkayman Date: Mon, 8 Aug 2022 00:06:46 +0300 Subject: [PATCH 3/6] :memo: README: fixed typos [ci skip] --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c042e0a3..024d7d83 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ -**TKO** serves as a foundation for `Knockout 4` which goal is to become a drop-in replacement and a feature-rich expansion of already existing KnockoutJS (3+) while adhearing new standarts and paradigms of web developmentent. Its built on top of current KnockoutJS featurelist while being [mostly compatible](https://www.tko.io/3to4) with it, further about it and build differences at [download](#download) section. +**TKO** serves as a foundation for `Knockout 4` which goal is to become a drop-in replacement and a feature-rich expansion of already existing KnockoutJS (3+) while adhering new standarts and paradigms of web developmentent. Its built on top of current KnockoutJS featurelist while being [mostly compatible](https://www.tko.io/3to4) with it, further about it and build differences at [download](#download) section. ### Download @@ -116,16 +116,15 @@ Currently there are 2 points of interest which further would be considered a wik The default package manager for monorepo currently is `npm` with the addition of [Lerna](https://lerna.js.org/docs/getting-started) as a viable choice for monorepo management. -First thing at getting familiar with the project monorepo is to look at `Makefile` at project root. Since its a separate file spanning entire repo, we will cover only the most used commands: +First thing at getting familiar with the project monorepo is to look at `./Makefile` at project root. Since its a separate file spanning entire repo, we will cover only the most commonly used commands: | Command | Effect | | ------- | ------ | | $ `git clone git@github.com:knockout/tko` | Clone the repository. -| $ `make` | Install all dependencies, build reference and compatibility versions of TKO at `builds/*/dist/*` (without any transpilation - needs proving). It is the `default` behavior, calling `all` directive. +| $ `make` | Install all dependencies, build *reference* and *compatibility* versions of TKO at `builds/*/dist/*` without any transpilation. It is the `default` makefile behavior calling `all` directive. | $ `make clean` | empties build directories `.../dist/*` and `package-lock.json`'s inside of every `package/*` and `builds/*` | $ `npm i` | Install local node packages and link tko modules | $ `make test` | Run all tests. See below. -| $ `make watch` | Run all tests and watch for changes. See below. | $ `make publish-unpublished` | Bump versions and publish to npm registry From 026dabecd481dcfeff5bf9abde5233b4a64ca15a Mon Sep 17 00:00:00 2001 From: ironkayman Date: Mon, 8 Aug 2022 00:32:09 +0300 Subject: [PATCH 4/6] :memo: README: update section about running tests [ci skip] --- README.md | 31 ++++++++++--------------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 024d7d83..d6664d9f 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ 4. [MJS](#imports-mjs) 3. [Sites](#sites) 3. [Using the Monporepo](#monorepo) + 1. [Test suit](#tests) 4. [Objectives](#objectives) 5. [Roadmap](#roadmap) 6. [License](#license) @@ -37,7 +38,7 @@ -**TKO** serves as a foundation for `Knockout 4` which goal is to become a drop-in replacement and a feature-rich expansion of already existing KnockoutJS (3+) while adhering new standarts and paradigms of web developmentent. Its built on top of current KnockoutJS featurelist while being [mostly compatible](https://www.tko.io/3to4) with it, further about it and build differences at [download](#download) section. +**TKO** serves as a foundation for `Knockout 4` which goal is to become a drop-in replacement and a feature-rich expansion of already existing KnockoutJS (3+) while adhering new standards and paradigms of web developmentent. Its built on top of current KnockoutJS featurelist while being [mostly compatible](https://www.tko.io/3to4) with it, further about it and build differences at [download](#download) section. ### Download @@ -127,33 +128,21 @@ First thing at getting familiar with the project monorepo is to look at `./Makef | $ `make test` | Run all tests. See below. | $ `make publish-unpublished` | Bump versions and publish to npm registry - ---- -> **TODO**: remove rollup info as current version uses ESbuild - -In each individual `packages/*/` directory, you can also run (presuming `rollup` and `karma` are installed globally): +In each individual `packages/*/` directory, you can also run (presuming `esbuild` and `karma` are installed globally): | Command | Effect | | --- | --- | -| $ `karma COMMAND ../../karma.conf.js [--once]` | Test the local package, where COMMAND is e.g. `start` or `run` -| $ `rollup -c ../../rollup.config.js` | Build the package into the local `dist/` - - -#### Testing with `yarn test` and `yarn watch` - -The `yarn test` and `yarn watch` commands can be used in the root directory, where it will run across all tests, or alternatively in any `packages/*/` directory to run tests -specific to that package. - -Optional arguments to `yarn test` include: +| $ `make test` | Test the local package, abstraction of `npx karma start ../../tools/karma.conf --once` +| $ `make` | Build the package into the local `dist/` -- `--sauce` — use Sauce Labs to test a variety of platforms; requires an account at Sauce Labs and `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` to be set in the environment. -- `--noStartConnect` — Do not start a new Sauce Connect proxy instance for every -test; requires that Sauce Connect be already running. +### Test suit -#### `visual.html` +```sh + make test +``` -Note that running `karma` or `rollup` will create a `visual.html` file that shows the proportional size of imports into each package. +Testing suit is build around Karma and Jasmine. The `make test` command can be used in the root directory, where it will run across all tests, or alternatively in any `packages/*/` directory to run tests specific to that package from their `spec` folders. ## Objectives From 25d7a481da01299c4c739d72565bec7a57c8a7fe Mon Sep 17 00:00:00 2001 From: ironkayman Date: Mon, 8 Aug 2022 00:37:25 +0300 Subject: [PATCH 5/6] :memo: README: update objectives: changed bundler name [ci skip] --- README.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index d6664d9f..793261c1 100644 --- a/README.md +++ b/README.md @@ -31,10 +31,7 @@ 7. [Shoutouts](#shoutouts) -
- ## Getting Started ---- @@ -61,8 +58,6 @@ This Knockout build has some backwards compatibility that is not in the referenc - *Compatibility* Build: https://cdn.jsdelivr.net/npm/@tko/build.knockout@4.0.0-alpha8/dist/build.knockout.min.js -
- ### Using TKO in a project Currently there is no default package root import due to availability of different builds listed below. Every TKO build supports all listed below module types: @@ -110,10 +105,7 @@ Currently there are 2 points of interest which further would be considered a wik - https://brianmhunt.github.io/knockout - Work In Profress wiki/docs for Knockout -
- ## Using the Monorepo ---- The default package manager for monorepo currently is `npm` with the addition of [Lerna](https://lerna.js.org/docs/getting-started) as a viable choice for monorepo management. @@ -142,14 +134,14 @@ In each individual `packages/*/` directory, you can also run (presuming `esbuild make test ``` -Testing suit is build around Karma and Jasmine. The `make test` command can be used in the root directory, where it will run across all tests, or alternatively in any `packages/*/` directory to run tests specific to that package from their `spec` folders. +Testing suit is build around Karma and Jasmine. The `make test` command can be used in the root directory, where it will run across all tests, or alternatively in any `packages/*/` directory to run tests specific to that package from their respective `spec` folders. ## Objectives TKO aims to become a base for future versions of Knockout. The objectives include: -- Modularization into ES6 and separate projects, with compilation using an ES6 compiler like [Rollup](http://rollupjs.org/). This solves several problems with Knockout, including: +- Modularization into ES6 and separate projects, with compilation using an ES6 compiler like [esbuild](https://esbuild.github.io/). This solves several problems with Knockout, including: - Some folks want to roll-their-own with e.g. removing components - Compilation is now with Closure compiler, which is actually transliterating – meaning the *debug* and *minified* versions have different code paths (mostly in the form of things exposed in *debug* being missing in the *minified* version) - The compilation of Knockout is just concatenation, leading to difficulties with maintainance, severance, and replacement From f88fd90520633aef633123090f00372d3924c63d Mon Sep 17 00:00:00 2001 From: ironkayman Date: Mon, 8 Aug 2022 00:42:30 +0300 Subject: [PATCH 6/6] :memo: README: update imports at "imports" section [ci skip] --- README.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 793261c1..bf919c60 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ Currently there is no default package root import due to availability of differe * ESM ```js - import ko from "@tko/build.reference/dist/index.js" + import ko from "@tko/build.reference/dist/index.js" ``` `ko` is default export so feel free to change import name on your desired. @@ -72,9 +72,9 @@ Currently there is no default package root import due to availability of differe * IIFE ```js - import "@tko/build.reference/dist/browser.js" - // or use already minified bundle - import "@tko/build.reference/dist/browser.min.js" + import "@tko/build.reference/dist/browser.js" + // or use already minified bundle + import "@tko/build.reference/dist/browser.min.js" ``` Imported namespace is available *only* as `tko`. @@ -82,18 +82,16 @@ Currently there is no default package root import due to availability of differe * CommonJS ```js - "@tko/build.reference/dist/index.cjs" + const ko = require("@tko/build.reference/dist/index.cjs") ``` - TODO - * MJS ```js - "@tko/build.reference/dist/index.mjs" + import ko from "@tko/build.reference/dist/index.mjs" ``` - TODO + `ko` is default export so feel free to change import name on your desired. > **Note**: you can check imported TKO version by looking at its namespace attribute `.version` in runtime. @@ -131,7 +129,7 @@ In each individual `packages/*/` directory, you can also run (presuming `esbuild ### Test suit ```sh - make test +make test ``` Testing suit is build around Karma and Jasmine. The `make test` command can be used in the root directory, where it will run across all tests, or alternatively in any `packages/*/` directory to run tests specific to that package from their respective `spec` folders.