{"id":22747219,"url":"https://github.com/one-com/knockout-transformations","last_synced_at":"2025-06-18T18:03:32.376Z","repository":{"id":66144393,"uuid":"30249168","full_name":"One-com/knockout-transformations","owner":"One-com","description":"Live transform methods for Knockout observable arrays","archived":false,"fork":false,"pushed_at":"2015-09-08T07:52:50.000Z","size":607,"stargazers_count":10,"open_issues_count":8,"forks_count":5,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-24T21:03:43.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/One-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-03T15:21:28.000Z","updated_at":"2021-08-08T11:58:31.000Z","dependencies_parsed_at":"2023-02-19T23:15:44.836Z","dependency_job_id":null,"html_url":"https://github.com/One-com/knockout-transformations","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Fknockout-transformations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Fknockout-transformations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Fknockout-transformations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Fknockout-transformations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/One-com","download_url":"https://codeload.github.com/One-com/knockout-transformations/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248872154,"owners_count":21175358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-11T03:13:46.100Z","updated_at":"2025-04-14T11:33:36.559Z","avatar_url":"https://github.com/One-com.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"knockout-transformations\n============\n\nLive transform methods for Knockout observable arrays.\n\nThis plugin adds observable `map`, `filter`, `indexBy` and `sortBy` features to observable arrays, so you can transform collections in arbitrary ways and have the results automatically update whenever the underlying source data changes.\n\nThe project initialy started out as a fork of https://github.com/SteveSanderson/knockout-projections and therefore owes a lot to this project. This project is licensed under Apache 2.0 by Microsoft Corporation and the part of the code derived from this project is constrained by this license. The rest of the code is also licensed under Apache 2.0 by One.com.\n\nInstallation\n============\n\nDownload a copy of `knockout-transformations.js` from [the `dist` directory](https://github.com/One-com/knockout-transformations/tree/master/dist) and reference it in your web application:\n\n```html\n\u003c!-- First reference KO itself --\u003e\n\u003cscript src='knockout-x.y.z.js'\u003e\u003c/script\u003e\n\u003c!-- Then reference knockout-transformations from dist --\u003e\n\u003cscript src='knockout-transformations.js'\u003e\u003c/script\u003e\n```\n\nBe sure to reference it *after* you reference Knockout itself.\n\nIf you are using NPM you can install knockout and knockout-transformations the following way:\n\n    npm install knockout knockout-transformations\n\nThen just reference the distribution files from `node_modules`.\n\nUsing require.js you can either point to the index file in `lib` or\nuse the individual transformations from located in `lib`.\n\nUsage\n=====\n\n**Mapping**\n\nMore info to follow. For now, here's a simple example:\n\n```js\nvar sourceItems = ko.observableArray([1, 2, 3, 4, 5]);\n```\n\nThere's a plain observable array. Now let's say we want to keep track of the squares of these values:\n\n```js\nvar squares = sourceItems.map(function(x) { return x*x; });\n```\n\nNow `squares` is an observable array containing `[1, 4, 9, 16, 25]`. Let's modify the source data:\n\n```js\nsourceItems.push(6);\n// 'squares' has automatically updated and now contains [1, 4, 9, 16, 25, 36]\n```\n\nThis works with any transformation of the source data, e.g.:\n\n```js\nsourceItems.reverse();\n// 'squares' now contains [36, 25, 16, 9, 4, 1]\n```\n\nThe key point of this library is that these transformations are done *efficiently*. Specifically, your callback\nfunction that performs the mapping is only called when strictly necessary (usually, that's only for newly-added\nitems). When you add new items to the source data, we *don't* need to re-map the existing ones. When you reorder\nthe source data, the output order is correspondingly changed *without* remapping anything.\n\nThis efficiency might not matter much if you're just squaring numbers, but when you are mapping complex nested\ngraphs of custom objects, it can be important to perform each mapping update with the minumum of work.\n\n**Filtering**\n\nAs well as `map`, this plugin also provides `filter`:\n\n```js\nvar evenSquares = squares.filter(function(x) { return x % 2 === 0; });\n// evenSquares is now an observable containing [36, 16, 4]\n\nsourceItems.push(9);\n// This has no effect on evenSquares, because 9*9=81 is odd\n\nsourceItems.push(10);\n// evenSquares now contains [36, 16, 4, 100]\n```\n\nAgain, your `filter` callbacks are only called when strictly necessary. Re-ordering or deleting source items don't\nrequire any refiltering - the output is simply updated to match. Only newly-added source items must be subjected\nto your `filter` callback.\n\n**Sorting**\n\nAs well as `map` and `filter`, this plugin also provides `sortBy`:\n\n```js\nvar sortedEvenSquares.sortBy(function (evenSquare, descending) {\n    return descending(evenSquare);\n});\n// sortedEvenSquares now contains [100, 36, 16, 4]\n```\n\nA more involved example:\n\n```js\nfunction Person(name, yearOfBirth) {\n    this.name = ko.observable(name);\n    this.yearOfBirth = ko.observable(yearOfBirth);\n}\n\nvar persons = ko.observableArray([\n    new Person(\"Marilyn Monroe\", 1926),\n    new Person(\"Abraham Lincoln\", 1809),\n    new Person(\"Mother Teresa\", 1910),\n    new Person(\"John F. Kennedy\", 1917),\n    new Person(\"Martin Luther King\", 1929),\n    new Person(\"Nelson Mandela\", 1918),\n    new Person(\"Winston Churchill\", 1874),\n    new Person(\"Bill Gates\", 1955),\n    new Person(\"Muhammad Ali\", 1942),\n    new Person(\"Mahatma Gandhi\", 1869),\n    new Person(\"Queen Elizabeth II\", 1926)\n]);\n\n// Persons sorted by name\nvar sortedByName = persons.sortBy(function (person) {\n    return person.name();\n});\n\n// sortedByName now contains\n// [\n//     new Person(\"Abraham Lincoln\", 1809),\n//     new Person(\"Bill Gates\", 1955),\n//     new Person(\"John F. Kennedy\", 1917),\n//     new Person(\"Mahatma Gandhi\", 1869),\n//     new Person(\"Marilyn Monroe\", 1926),\n//     new Person(\"Martin Luther King\", 1929),\n//     new Person(\"Mother Teresa\", 1910),\n//     new Person(\"Muhammad Ali\", 1942)\n//     new Person(\"Nelson Mandela\", 1918),\n//     new Person(\"Queen Elizabeth II\", 1926),\n//     new Person(\"Winston Churchill\", 1874),\n// ]\n\n// Persons sorted by year of birth descending and then by name\nvar sortedByYearOfBirthAndThenName = persons.sortBy(function (person, descending) {\n    return [descending(person.yearOfBirth()), person.name()];\n});\n\n// sortedByYearOfBirthAndThenName now contains\n// [\n//     new Person(\"Abraham Lincoln\", 1809),\n//     new Person(\"Mahatma Gandhi\", 1869),\n//     new Person(\"Winston Churchill\", 1874),\n//     new Person(\"Mother Teresa\", 1910),\n//     new Person(\"John F. Kennedy\", 1917),\n//     new Person(\"Nelson Mandela\", 1918),\n//     new Person(\"Martin Luther King\", 1929),\n//     new Person(\"Bill Gates\", 1955),\n//     new Person(\"Marilyn Monroe\", 1926),\n//     new Person(\"Queen Elizabeth II\", 1926),\n//     new Person(\"Muhammad Ali\", 1942)\n// ]\n```\n\nThe sorted list is only updated when items are added or removed and when properties that are sorted on changes.\n\n**Indexing**\n\nThis transformation provides you with live updated index on a key returned\nby the given function. In contrast to the `map`, `filter` and `sortBy`\nthis transformation returns an object and is therefore not a candidate for\nchaining.\n\n```js\nvar squareIndex = squares.indexBy(function (square) {\n    return square % 2 === 0 ? 'even' : 'odd';\n});\n\n// squareIndex now contains\n// { even: [36, 16, 4], odd: [25, 9, 1] }\n36, 25, 16, 9, 4, 1\n```\n\nA more involved example using the persons defined in the sorting example:\n\n```js\n\n// Persons indexed by year of birth\nvar personsIndexedByYearBirth = persons.indexBy(function (person) {\n    return person.yearOfBirth();\n});\n\n// personsIndexedByYearBirth now contains\n// {\n//     1809: [new Person(\"Abraham Lincoln\", 1809)],\n//     1869: [new Person(\"Mahatma Gandhi\", 1869)],\n//     1874: [new Person(\"Winston Churchill\", 1874)],\n//     1910: [new Person(\"Mother Teresa\", 1910)],\n//     1917: [new Person(\"John F. Kennedy\", 1917)],\n//     1918: [new Person(\"Nelson Mandela\", 1918)],\n//     1929: [new Person(\"Martin Luther King\", 1929)],\n//     1955: [new Person(\"Bill Gates\", 1955)],\n//     1926: [new Person(\"Marilyn Monroe\", 1926),\n//            new Person(\"Queen Elizabeth II\", 1926)],\n//     1942: [new Person(\"Muhammad Ali\", 1942)]\n// }\n\n// Persons indexed uniquely by name.\n// Notice unique indexes requires items to map to distint keys;\n// otherwise an exception is thrown.\nvar personsIndexedByName = persons.uniqueIndexBy(function (person) {\n    return person.name();\n});\n\n// personsIndexedByName now contains\n// {\n//     \"Abraham Lincoln\": new Person(\"Abraham Lincoln\", 1809),\n//     \"Mahatma Gandhi\": new Person(\"Mahatma Gandhi\", 1869),\n//     \"Winston Churchill\": new Person(\"Winston Churchill\", 1874),\n//     \"Mother Teresa\": new Person(\"Mother Teresa\", 1910),\n//     \"John F. Kennedy\": new Person(\"John F. Kennedy\", 1917),\n//     \"Nelson Mandela\": new Person(\"Nelson Mandela\", 1918),\n//     \"Martin Luther King\": new Person(\"Martin Luther King\", 1929),\n//     \"Bill Gates\": new Person(\"Bill Gates\", 1955),\n//     \"Marilyn Monroe\": new Person(\"Marilyn Monroe\", 1926),\n//     \"Queen Elizabeth II\": new Person(\"Queen Elizabeth II\", 1926),\n//     \"Muhammad Ali\": new Person(\"Muhammad Ali\", 1942)\n// }\n```\n\nIt is also possible to create an index on multiple keys to following way:\n\n```js\nvar texts = ko.observableArray(['foo', 'bar', 'baz', 'qux', 'quux']);\n// Index texts by\nvar indexedTexts = texts.indexBy(function (text) {\n    var firstLetter = text[0];\n    var lastLetter = text[text.length - 1];\n    return [firstLetter, lastLetter];\n});\n\n// indexedTexts now contains\n// {\n//     f: ['foo'],\n//     b: ['bar', 'baz'],\n//     q: ['qux', 'quux'],\n//     o: ['foo'],\n//     r: ['bar'],\n//     z: ['baz'],\n//     x: ['qux', 'quux']\n// }\n```\n\n**Chaining**\n\nThe above code also demonstrates that you can chain together successive `map`, `filter` and `sortBy` transformations.\n\nWhen the underlying data changes, the effects will ripple out through the chain of computed arrays with the\nminimum necessary invocation of your `map`, `filter` and `sortBy` callbacks.\n\nHow to build from source\n========================\n\nFirst, install [NPM](https://npmjs.org/) if you don't already have it. It comes with Node.js.\n\nSecond, install Grunt globally, if you don't already have it:\n\n    npm install -g grunt-cli\n\nThird, use NPM to download all the dependencies for this module:\n\n    cd wherever_you_cloned_this_repo\n    npm install\n\nNow you can build the package (linting and running tests along the way):\n\n    grunt\n\nOr you can just run the linting tool and tests:\n\n    grunt test\n\nOr you can make Grunt watch for changes to the sources/specs and auto-rebuild after each change:\n\n    grunt watch\n\nThe browser-ready output files will be dumped at the following locations:\n\n * `dist/knockout-transformations.js`\n * `dist/knockout-transformations.min.js`\n\nLicense - Apache 2.0\n====================\n\nCopyright 2015 One.com\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fone-com%2Fknockout-transformations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fone-com%2Fknockout-transformations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fone-com%2Fknockout-transformations/lists"}