{"id":14384342,"url":"https://github.com/calculang/calculang","last_synced_at":"2025-08-23T17:31:41.889Z","repository":{"id":43786402,"uuid":"420200901","full_name":"calculang/calculang","owner":"calculang","description":"calculang is a language for calculations 🧮💬👩‍💻","archived":false,"fork":false,"pushed_at":"2024-08-26T09:42:49.000Z","size":2676,"stargazers_count":49,"open_issues_count":104,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-13T06:40:24.707Z","etag":null,"topics":["calculang","calculations","functional-programming","javascript","modeling","modelling","models","numbers"],"latest_commit_sha":null,"homepage":"https://calculang.dev","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/calculang.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-22T18:18:23.000Z","updated_at":"2024-12-10T08:40:34.000Z","dependencies_parsed_at":"2024-05-14T09:55:07.109Z","dependency_job_id":"24cff52e-8733-4ecf-b9f2-11c285317121","html_url":"https://github.com/calculang/calculang","commit_stats":{"total_commits":76,"total_committers":2,"mean_commits":38.0,"dds":0.07894736842105265,"last_synced_commit":"f2b62ae69829b505ed1ed25ec83a0e38d9bccf5f"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calculang%2Fcalculang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calculang%2Fcalculang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calculang%2Fcalculang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calculang%2Fcalculang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/calculang","download_url":"https://codeload.github.com/calculang/calculang/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230716466,"owners_count":18269764,"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":["calculang","calculations","functional-programming","javascript","modeling","modelling","models","numbers"],"created_at":"2024-08-28T18:01:19.185Z","updated_at":"2025-08-23T17:31:41.879Z","avatar_url":"https://github.com/calculang.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# calculang\n\ncalculang is a language for calculations.\n\n## motivation: separation of concerns\n\ncalculang is domain-specific to calculations and it proposes a separation of concerns: **calculations separate from general programming**.\n\nThis makes it easier to reason about calculations, empowers specialised tooling, and enables **frictionless transparency and certainty** about calculations.\n\nA language for calculations also generalises more readily than more rigid systems or tools, enabling **unity of calculations** and process (all ends).\n\nA language for calculations can integrate freely with **established best-practice development, testing, and controls approach and tooling** for languages.\n\n## chronicles of calculang (Feb 2025) ⚡\n\nSee the note [chronicles of calculang](https://calculang.dev/#chronicles-of-calculang-feb-2025-published-work-and-status) on [calculang.dev](https://calculang.dev) for some recent progress and status update.\n\n## examples\n\nVisit [calculang.dev](https://calculang.dev) for the official website and examples!\n\nI post about calculang and sometimes models using calculang on my [CalcWithDec](https://calcwithdec.dev/) blog.\n\nMy (older) [ObservableHQ collection](https://observablehq.com/collection/@declann/calculang) including additional models including ferns, donuts and pi estimation models!\n\n\n## follow calculang 📫\n\nFor calculang updates follow [@calculang](https://twitter.com/calculang) on Twitter, or follow [@calculang@fosstodon.org](https://fosstodon.org/@calculang) from any(!) [Mastodon](https://joinmastodon.org/) server 🐘 (I mainly post of Mastodon)\n\n## compiler\n\n`cul-js` CLI compiles calculang into Javascript and provides information about the resulting model (introspection). (new: use the experimental `all_cul` branch for a compiler that works in your browser)\n\n## usage\n\nInstallation:\n\n```shell\nnpm install --save-dev @calculang/calculang-js\n```\n\nCompilation:\n\n```shell\ncul-js compile entrypoint.cul.js\n```\n\nThis creates `entrypoint.js` (alongside entrypoint.cul.js). This is a UMD Javascript bundle, with sourcemap `entrypoint.js.map`.\n\nUse the `--memo` option to turn on memoization. Memoization typically **dramatically** helps execution of models.\n\nIntrospection:\n\n```shell\ncul-js introspect entrypoint.cul.js\n```\n\nGraph, using `dot` command from graphviz (install separately):\n\n```shell\ncul-js dot entrypoint.cul.js | dot -Tsvg \u003e temp.svg\nstart temp.svg\n```\n\n## design principles/features\n\n**Modularity**:\n\nA key design focus for calculang is scalability. To this end calculang models can be defined in modular fashion and recycled for varying usecases.\n\nModels-of-models is a useful concept in considering model design. A design suggestion is to develop very general models and apply these in use- or application-specific models; in this way the models can support a wider range of usecases.\n\n**Input inference**:\n\nInputs to function calls in calculang are inferred by the compiler, based on a graph of inputs and functions in the complete model being compiled.\n\nThis reduces code boilerplate, but more fundamentally it promotes recycling of models: we shouldn't code the wiring between functions manually because it will differ from one usecase to the next.\n\n**Inheritance of parent functions and overriding**:\n\nIn modular development, calculang gives precedence for a given function call to functions defined closer to the entrypoint or model root, rather than closer to the call.\n\nIn this way \"parent\" models can override the functionality of \"child\" models, and this supports recycling of very general models.\n\nThe overriden functionality can be defined in terms of the child function (using an interim '_' modifier), for example to inflate the price in a 'base' model might involve\n\n```javascript\nimport { price_ as price_base } from './base.cul.js';\n\nexport const price = price_base() * 1.1;\n```\n\n**Javascript**:\n\nIn calculang-js implementation calculang models can interact with Javascript. You should keep Javascript-specific code in separate .js files/packages.\n\nThis interaction, done carefully, opens up many usecases. Not least, integration and co-ordination with (and of) other systems.\n\n## status\n\nInitial implementation scales better conceptually vs. practically, but is nonetheless useful for an array of simple applications and carefully bounded problems beyond that.\n\nThis is another way of saying: some technical creativity helps to get the most out of the existing implementation. Careful interaction with Javascript leaves enormous scope open here!\n\n## roadmap\n\nv0.1.0-alpha1+ : some mini releases to introduce developed/proposed features, tests, cleanup code\n\nv0.1+.0 : more tests, examples, integrations, documentation, logo, community focus,  maybe REPL, website, blog, barebones browser extension, barebones VSCode extension, alt. bundler?, eventually show HN, review license/CLA/etc, CI/CD optimisation\n\nPost: alt. implementations? e.g. Rust?\n\n## help wanted\n\nExtension authors for browsers/VSCode. These can be independent projects. Similar Re integrations (incl. Excel, Python \u0026 notebooks, Julia \u0026 Pluto.jl).\n\nFrontend developers for blog/websites and community model frontends including tools.\n\nCommunity models and web apps, visualizations/explorables (calculang.party?).\n\nAll developers to get feedback/discuss/think re motivation and implementation/technical improvements.\n\n## more motivation\n\ncalculang is motivated to make models: the workings of numbers, more accessible. Bret Victor included points around this in his blog post on [What can a technologist do about Climate Change (a personal view)](http://worrydream.com/ClimateChange), particularly relevant at [Media for Understanding Situations](http://worrydream.com/ClimateChange/#media).\n\nAlso good by Bret Victor, regarding interfaces to models: [Explorable Explanations](http://worrydream.com/#!/ExplorableExplanations).\n\nMany ideas along different lines of interaction with models become clearer when we separate concerns in the way that a language for calculations proposes.\n\n## contributing\n\n[CONTRIBUTING.md](./CONTRIBUTING.md) contains brief development/contributing notes including build steps.\n\n## license\n\nCode in this repository is free software licensed under the [GNU Affero General Public License Version 3](LICENSE).\n\ncalculang is made with ❤️ and 🧉\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalculang%2Fcalculang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcalculang%2Fcalculang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalculang%2Fcalculang/lists"}