{"id":28050628,"url":"https://github.com/notmywing/stoikts","last_synced_at":"2025-05-12T00:37:17.759Z","repository":{"id":64586849,"uuid":"576380605","full_name":"NotMyWing/StoikTS","owner":"NotMyWing","description":"Chemical formulae parser/tokenizer written in TypeScript.","archived":false,"fork":false,"pushed_at":"2022-12-14T05:36:28.000Z","size":148,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-12T00:37:17.381Z","etag":null,"topics":["chemical-formula","chemistry","javascript","javascript-library","stoichiometry","typescript","typescript-library"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/stoik","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NotMyWing.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":"2022-12-09T17:54:07.000Z","updated_at":"2023-08-18T10:30:19.000Z","dependencies_parsed_at":"2023-01-28T17:15:30.303Z","dependency_job_id":null,"html_url":"https://github.com/NotMyWing/StoikTS","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotMyWing%2FStoikTS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotMyWing%2FStoikTS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotMyWing%2FStoikTS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotMyWing%2FStoikTS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NotMyWing","download_url":"https://codeload.github.com/NotMyWing/StoikTS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253655915,"owners_count":21943072,"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":["chemical-formula","chemistry","javascript","javascript-library","stoichiometry","typescript","typescript-library"],"created_at":"2025-05-12T00:37:14.741Z","updated_at":"2025-05-12T00:37:17.729Z","avatar_url":"https://github.com/NotMyWing.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stoik\nStoik is a TypeScript library for parsing and evaluating chemical formulas.\n\n## Installation\nTo install Stoik, run the following command:\n\n```\nnpm install stoik\n```\n\n## Usage\n\nTo use Stoik in your project, import the `evaluate` function as well as any other necessary functions for your project:\n\n```js\nimport { tokenize, evaluate, toRPN, Molecule } from \"stoik\";\n```\n\nTo evaluate a chemical formula using Stoik, you can use the `evaluate` function. This function takes a chemical formula as input and returns a `Molecule` instance, which is essentially an extension of Map and contains the atoms and their frequencies in the molecule. For example:\n\n```js\nconst formula = \"H2O\";\n\nevaluate(formula); // Map {\"H\" =\u003e 2, \"O\" =\u003e 1}\n\n// Formulas can consist of fairly complicated operations as well.\nevaluate(\"5(H2O)3((FeW)5CrMo2V)6CoMnSi\");\n\n// The result of the expression above is equivalent to:\nnew Molecule([\n\t[\"H\", 30],\n\t[\"Co\", 5],\n\t[\"Cr\", 30],\n\t[\"Fe\", 150],\n\t[\"Mn\", 5],\n\t[\"Mo\", 60],\n\t[\"O\", 15],\n\t[\"Si\", 5],\n\t[\"V\", 30],\n\t[\"W\", 150],\n]);\n```\n\n### Tokenization and Parsing\n\nAlternatively, it's possible to `evaluate` formulas step-by-step, if you need to alter any of the steps.\n\nThe `tokenize` function combines the tokenization and parsing functionality. It is capable of detecting malformed formulas to some extent.\nHowever, if the input is not a valid formula, the function is not guaranteed to return a sequence that will correctly evaluate into a Molecule.\n\n```js\n// First, tokenize the formula to get a Denque sequence of tokens.\nconst tokens = tokenize(formula);\n// new Denque([\n//   [TokenType.Atom, \"H\"],\n//   [TokenType.Subscript],\n//   [TokenType.Number, 2],\n//   [TokenType.Add]\n//   [TokenType.Atom, \"O\"]\n// ]);\n```\n\nBefore supplying the tokens to `evaluate`, they first have to be converted to the Reverse Polish Notation using `toRPN`.\nLike `tokenize`, this function is not guaranteed to return a valid sequence of tokens if the input is inherently incorrect.\n\n```js\n// Next, convert the tokens to Reverse Polish Notation (RPN) using the toRPN function. Note the different order.\nconst RPN = toRPN(tokens);\n// new Denque([\n//   [TokenType.Atom, \"H\"],\n//   [TokenType.Number, 2],\n//   [TokenType.Subscript],\n//   [TokenType.Atom, \"O\"],\n//   [TokenType.Add]\n// ]);\n```\n\nFinally, the RPN token sequence can be supplied to `evaluate` to evaluate the formula.\nThis will throw a concise error if the input is incorrect.\n\n```js\nevaluate(RPN); // Map {\"H\" =\u003e 2, \"O\" =\u003e 1}\n```\n\n## Molecule Class\n\nThe `Molecule` class includes methods for performing basic arithmetic operations on molecules.\nBy default, these methods return new `Molecule` instances, which means that they do not mutate the original molecule.\nHowever, each method also has a mutable counterpart (e.g. `add` and `addMut`) that can be used to modify the original molecule instead.\n\nAn `AtomLiteral` is a type that represents a valid atom in a chemical molecule. It must be either a single uppercase letter (e.g. \"H\" for hydrogen), or a combination of an uppercase letter followed by a lowercase letter (e.g. \"Cl\" for chlorine).\n\nMolecule objects can be constructed in several ways:\n* With no arguments, to create an empty molecule\n* With a single `AtomLiteral` argument, to create a molecule containing a single atom at a frequency of 1\n* With a single `AtomLiteral` and a `number` argument, to create a molecule containing a single atom at a specified frequency\n* With a `Molecule` argument, to create a new molecule with the same atoms and frequencies as the input molecule\n* With an array of tuples, where each tuple contains an `AtomLiteral` and an optional `number`, to create a molecule containing the atoms and frequencies specified in the input array\n\n\nThe Molecule class also contains several methods for manipulating molecules:\n* The `set` method can be used to add or update the frequency of an atom in the molecule\n* The `add` method can be used to add a molecule to this molecule\n* The `subtract` method can be used to subtract a molecule from this molecule\n* The `multiply` method can be used to multiply this molecule by a number\n* All other methods provided by the standard `Map` class\n\nIn addition, the `Molecule` class has a `fromAtom` static method that can be used to quickly create a molecule containing a single atom at a specified frequency.\n\n## Design and Implementation\n\nStoik uses a combination of recursive descent parsing and the Shunting-yard algorithm to parse and evaluate chemical formulas. The `tokenize` function uses a simple state machine to split the input string into tokens, and the `evaluate` function uses a stack to evaluate the formula in RPN.\n\n## License\n\nStoik is licensed under the LGPL 3.0 license. See the [LICENSE](./LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotmywing%2Fstoikts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotmywing%2Fstoikts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotmywing%2Fstoikts/lists"}