{"id":22525520,"url":"https://github.com/sjohnsonaz/cascade","last_synced_at":"2025-08-03T21:32:34.025Z","repository":{"id":40910321,"uuid":"58600699","full_name":"sjohnsonaz/cascade","owner":"sjohnsonaz","description":"A modern library for creating user interfaces.","archived":false,"fork":false,"pushed_at":"2023-01-07T02:17:21.000Z","size":3306,"stargazers_count":49,"open_issues_count":19,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-24T13:36:18.054Z","etag":null,"topics":["cascade","component","computed","jsx","mvvm","observable","observablearray","typescript","virtual-dom","virtualnode"],"latest_commit_sha":null,"homepage":"https://sjohnsonaz.github.io/cascade","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sjohnsonaz.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":"2016-05-12T02:33:49.000Z","updated_at":"2024-11-01T11:20:38.000Z","dependencies_parsed_at":"2023-02-06T10:31:35.281Z","dependency_job_id":null,"html_url":"https://github.com/sjohnsonaz/cascade","commit_stats":null,"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjohnsonaz%2Fcascade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjohnsonaz%2Fcascade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjohnsonaz%2Fcascade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjohnsonaz%2Fcascade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sjohnsonaz","download_url":"https://codeload.github.com/sjohnsonaz/cascade/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228219837,"owners_count":17887058,"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":["cascade","component","computed","jsx","mvvm","observable","observablearray","typescript","virtual-dom","virtualnode"],"created_at":"2024-12-07T06:10:28.075Z","updated_at":"2024-12-07T06:10:28.824Z","avatar_url":"https://github.com/sjohnsonaz.png","language":"TypeScript","readme":"# Cascade\n\n![](https://github.com/sjohnsonaz/cascade/workflows/Node%20CI/badge.svg) [![npm version](https://badge.fury.io/js/cascade.svg)](https://badge.fury.io/js/cascade)\n\nA JavaScript/TypeScript library for creating modern user interfaces. It combines Reactive ViewModels with Functional DOM Components to create seamless flow of data.\n\n## Reactive ViewModels\n\nCascade builds ViewModels with reactive properties to synchronize data. Properties may be marked as observable, so that changes may be watched, or computed, which then watch for changes in related observables. With this, a dynamic tree of data may be built, all which is updated automatically.\n\nFurthermore, any Functional DOM Component which references an observable or computed, will be updated automatically.\n\n### TypeScript decorators\n\nSimply use the `@observable` decorator, which will automatically detect if the property is a value, an array, or a getter function.  Computed values must be declared as a getter, and arrays must be declared with their types.  Observable hashes may be created with `@hash`.  \n\n\u003e **Note:** Decorators depend on TypeScript. You must set `\"experimentalDecorators\": true` in your `tsconfig.json` file.\n\n```typescript\nclass User {\n    @observable firstName: string = '';\n    @observable lastName: string = '';\n    @observable get fullName() {\n        return this.firstName + ' ' + this.lastName;\n    }\n    @observable list: number[] = [1, 2, 3, 4];\n    @array array: number[] = [5, 6, 7, 8];\n    @hash hash: {} = {\n        'property': 'value'\n    };\n}\n```\n\n\u003e **Note:** Type detection for arrays depends on the optional package `reflect-metadata`. You must also set `\"emitDecoratorMetadata\": true` in your `tsconfig.json` file. For IE10 and below, you must also include `es6-shim` or similar polyfills.  If you don't wish to install polyfills, then you must use `@array` instead of `@observable`.\n\n### JavaScript usage\n\nYou may also create observable properties directly.\n\n```typescript\nCascade.createObservable\u003cT\u003e(obj: any, property: string, value?: T);\n\nCascade.createObservableArray\u003cT\u003e(obj: any, property: string, value?: Array\u003cT\u003e);\n\nCascade.createObservableHash\u003cT\u003e(obj: any, property: string, value?: IHash\u003cT\u003e);\n\nCascade.createComputed\u003cT\u003e(obj: any, property: string, definition: (n?: T) =\u003e T, defer?: boolean, setter?: (n: T) =\u003e any);\n```\n\nYou may also create the observables as objects. Keep in mind, these are accessed as methods instead of direct usage.\n\n```typescript\nObservable\u003cT\u003e(value?: T);\n\nObservableArray\u003cT\u003e(value?: Array\u003cT\u003e);\n\nObservableHash\u003cT\u003e(value?: IHash\u003cT\u003e);\n\nComputed\u003cT\u003e(definition: (n?: T) =\u003e T, defer: boolean = false, thisArg?: any, setter?: (n: T) =\u003e any);\n```\n\n\u003e **Note:** Internet Explorer does not support `ObservableHash`.  It also requires `ObservableArray` values to be modified by function calls instead of setters.\n\u003e \n\u003e In modern browsers which support `Proxy` objects, we can simply modify indexed values with:\n\u003e \n\u003e `viewModel.list[4] = 5;`\n\u003e \n\u003e However, in Internet Explorer, we would need to write:\n\u003e \n\u003e `viewModel.list.set(4, 5);`\n\n## Functional DOM Components\n\nCascade uses either JSX or direct JavaScript calls to create a Virtual Dom. These Virtual Nodes can then be rendered into DOM Nodes for display.\n\n```typescript\nCascade.createElement\u003cT extends Object\u003e(\n    type: string | Component,\n    props: T,\n    ...children: Array\u003cany\u003e\n): IVirtualNode\u003cany\u003e;\n```\n\nComponents may be defined by simply extending the Component class. Any property which references an observable will cause the Component to render any time the observable updates.\n\n```typescript\ninterface IUserViewProps {\n    user: User;\n}\n\nclass UserView extends Component\u003cIUserViewProps\u003e {\n    render() {\n        return (\n            \u003cdiv\u003e{this.props.user.fullName}\u003c/div\u003e\n        );\n    }\n}\n```\n\n### Using Components\n\nComponents can then be rendered by either calling\n\n```typescript\nCascade.createElement(UserView, { user: User });\n```\n\nor with JSX by calling\n\n```typescript\n\u003cUserView user={User} /\u003e\n```\n\n\u003e **Note** Using JSX requires the options `\"jsx\": \"react\"` and `\"reactNamespace\": \"Cascade\"` in your `tsconfig.json` file. `Cascade` must also be imported into any `.jsx` or `.tsx` file.\n\n### Component and VirtualNode Properties\n\nComponents and VirtualNodes have optional props\n\n`key: string`\n\nSpecifying a `key` for a Component or VirtualNode will improve rendering speeds in certain cases. This is a string, which should be unique to that node within its parent. It is most useful for a set of children which change often, such as arrays or conditional children.\n\n`ref: (n: Node) =\u003e void`\n\nA `ref` callback will receive the resulting `Node` whenever the Component or VirtualNode is rendered for the first time. This is useful for directly modifying the `Node` after rendering.\n\n## Rendering\n\nCascade will render directly to any DOM node specified. Simply call\n\n```typescript\nCascade.render(\n    node: HTMLElement | string,\n    virtualNode: IVirtualNode\u003cany\u003e\n): void;\n```\n\nFor example\n\n```typescript\nCascade.render(\n    document.getElementById('root'),\n    \u003cUserView user={User} /\u003e\n);\n```\n\n## Troubleshooting and Optimization\n\n### Computed Subscriptions\n\nComputed properties subscribe to observables simply by reading them.  So any property that is read, will generate a subscription.  If you don't want to subscribe, use `Cascade.peek(obj: any, property: string)` to read the value without subscribing.\n\nAlso, if you need to call methods inside of a computed, those methods may read from observables as well.  This behavior may or may not be what you intend.  To protect against this, use `Cascade.wrapContext(callback: () =\u003e any, thisArg?: any)`, which will capture any generated subscriptions without actually subscribing to them.\n\n### Component Subscriptions\n\nComponents manage their subscriptions through the `Component.root` computed property.  Internally, this calls the `Component.render` method, so any observable read while rendering will generate a subscription.  In order to reduce re-renders, read observable properites as late as possible.  Meaning, it's better to read inside a child component, than inside a parent and then pass the value into the child.  This way only the child re-renders when the value is updated.\n\n### Multiple Installations\n\nIf a Component or Computed is not correctly updating, there may be more than one copy of Cascade referenced.  There must be exactly one copy for subscriptions to be tracked correctly.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjohnsonaz%2Fcascade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsjohnsonaz%2Fcascade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjohnsonaz%2Fcascade/lists"}