{"_id":"@3xpo/smol-toml","_rev":"1-81aa4504b8cc29df64357c9fd3929d28","name":"@3xpo/smol-toml","dist-tags":{"latest":"1.1.3-fix-1"},"versions":{"1.1.2":{"name":"@3xpo/smol-toml","version":"1.1.2","keywords":["toml","parser","serializer"],"description":"A small, fast, and correct TOML parser/serializer","repository":{"type":"git","url":"git+ssh://git@github.com/squirrelchat/smol-toml.git"},"author":{"name":"Cynthia","email":"cyyynthia@borkenware.com"},"license":"BSD-3-Clause","type":"module","engines":{"node":">= 18","pnpm":">= 8"},"devDependencies":{"@iarna/toml":"3.0.0","@ltd/j-toml":"^1.38.0","@rollup/plugin-terser":"^0.4.3","@rollup/plugin-typescript":"^11.1.3","@tsconfig/esm":"^1.0.4","@tsconfig/node-lts":"^18.12.5","@tsconfig/strictest":"^2.0.1","@types/node":"^20.5.7","@vitest/ui":"^0.31.4","fast-toml":"^0.5.4","rollup":"^3.28.1","tslib":"^2.6.2","typescript":"^5.2.2","vitest":"^0.31.4"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js","require":"./dist/index.cjs","import":"./dist/index.js"}},"types":"./dist/index.d.ts","main":"./dist/index.cjs","module":"./dist/index.js","scripts":{"build":"rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript","test":"vitest","test-ui":"vitest --ui","bench":"vitest bench"},"bugs":{"url":"https://github.com/squirrelchat/smol-toml/issues"},"homepage":"https://github.com/squirrelchat/smol-toml#readme","_id":"@3xpo/smol-toml@1.1.2","_integrity":"sha512-nZTeC4kLzIXmkE2jSsJcmNRQxtIZcI27AbK+avwsWX5EvohO7K9dDmfTS06MKQOrtq2monVjEfwM5miPYDT9mQ==","_resolved":"/tmp/5b7d51cb36c3542c97b6eb1f77277238/3xpo-smol-toml-1.1.2.tgz","_from":"file:3xpo-smol-toml-1.1.2.tgz","_nodeVersion":"20.5.1","_npmVersion":"9.8.0","dist":{"integrity":"sha512-nZTeC4kLzIXmkE2jSsJcmNRQxtIZcI27AbK+avwsWX5EvohO7K9dDmfTS06MKQOrtq2monVjEfwM5miPYDT9mQ==","shasum":"2b07464bfd88ea66507b931ee5dbc5584a2db12b","tarball":"https://registry.npmjs.org/@3xpo/smol-toml/-/smol-toml-1.1.2.tgz","fileCount":17,"unpackedSize":215885,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDJfVNOFysbunTYkVtp6wPv3m904lOVbcxMt/yI2xPP+AiEA+fEMqoxOxJwS3Yn2PZ1Wjf3jPKuN6Uyzm5WJtYqyI8E="}]},"_npmUser":{"name":"exponentialworkload","email":"cc@aaathats3as.com"},"directories":{},"maintainers":[{"name":"exponentialworkload","email":"cc@aaathats3as.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/smol-toml_1.1.2_1693368311581_0.849966563608644"},"_hasShrinkwrap":false},"1.1.3-fix-1":{"name":"@3xpo/smol-toml","version":"1.1.3-fix-1","keywords":["toml","parser","serializer"],"description":"A small, fast, and correct TOML parser/serializer","repository":{"type":"git","url":"git+ssh://git@github.com/squirrelchat/smol-toml.git"},"author":{"name":"Cynthia","email":"cyyynthia@borkenware.com"},"license":"BSD-3-Clause","engines":{"node":">= 18","pnpm":">= 8"},"devDependencies":{"@iarna/toml":"3.0.0","@ltd/j-toml":"^1.38.0","@rollup/plugin-terser":"^0.4.3","@rollup/plugin-typescript":"^11.1.3","@tsconfig/esm":"^1.0.4","@tsconfig/node-lts":"^18.12.5","@tsconfig/strictest":"^2.0.1","@types/node":"^20.5.7","@vitest/ui":"^0.31.4","fast-toml":"^0.5.4","rollup":"^3.28.1","tslib":"^2.6.2","typescript":"^5.2.2","vitest":"^0.31.4"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.cjs","import":"./dist/index.mjs","default":"./dist/index.mjs"}},"types":"./dist/index.d.ts","main":"./dist/index.cjs","module":"./dist/index.mjs","scripts":{"build":"rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript","test":"vitest","test-ui":"vitest --ui","bench":"vitest bench"},"bugs":{"url":"https://github.com/squirrelchat/smol-toml/issues"},"homepage":"https://github.com/squirrelchat/smol-toml#readme","_id":"@3xpo/smol-toml@1.1.3-fix-1","_integrity":"sha512-Rxp+HlM5BvRtImwOozrQrMvHRiGzfw//XHZUncpzgkzMcvJKISAmoGfpEwTvbeGzrEJ33CLrhdeRR0xhLFFV5A==","_resolved":"/tmp/083478c286b94b6e1d42d2eed51ac169/3xpo-smol-toml-1.1.3-fix-1.tgz","_from":"file:3xpo-smol-toml-1.1.3-fix-1.tgz","_nodeVersion":"20.5.1","_npmVersion":"9.8.0","dist":{"integrity":"sha512-Rxp+HlM5BvRtImwOozrQrMvHRiGzfw//XHZUncpzgkzMcvJKISAmoGfpEwTvbeGzrEJ33CLrhdeRR0xhLFFV5A==","shasum":"86d87ca23f0da66c92656b583a3f6db7b0fd0897","tarball":"https://registry.npmjs.org/@3xpo/smol-toml/-/smol-toml-1.1.3-fix-1.tgz","fileCount":17,"unpackedSize":215874,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIC4KoOivbctzU0gjvjN9vx21qYM5J0NLh4exBurRjyl9AiBxpOFevQtA7IGxzguEgKMQle85zp+PwKlnNGda5X99Eg=="}]},"_npmUser":{"name":"exponentialworkload","email":"cc@aaathats3as.com"},"directories":{},"maintainers":[{"name":"exponentialworkload","email":"cc@aaathats3as.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/smol-toml_1.1.3-fix-1_1693368772726_0.18038126847051483"},"_hasShrinkwrap":false}},"time":{"created":"2023-08-30T04:05:11.495Z","1.1.2":"2023-08-30T04:05:11.872Z","modified":"2023-08-30T04:12:53.153Z","1.1.3-fix-1":"2023-08-30T04:12:52.963Z"},"maintainers":[{"name":"exponentialworkload","email":"cc@aaathats3as.com"}],"description":"A small, fast, and correct TOML parser/serializer","homepage":"https://github.com/squirrelchat/smol-toml#readme","keywords":["toml","parser","serializer"],"repository":{"type":"git","url":"git+ssh://git@github.com/squirrelchat/smol-toml.git"},"author":{"name":"Cynthia","email":"cyyynthia@borkenware.com"},"bugs":{"url":"https://github.com/squirrelchat/smol-toml/issues"},"license":"BSD-3-Clause","readme":"# smol-toml\n[![TOML 1.0.0](https://img.shields.io/badge/TOML-1.0.0-9c4221?style=flat-square)](https://toml.io/en/v1.0.0)\n[![License](https://img.shields.io/github/license/squirrelchat/smol-toml.svg?style=flat-square)](https://github.com/squirrelchat/smol-toml/blob/mistress/LICENSE)\n[![npm](https://img.shields.io/npm/v/smol-toml?style=flat-square)](https://npm.im/smol-toml)\n\nA small, fast, and correct TOML parser and serializer. smol-toml is fully(ish) spec-compliant with TOML v1.0.0.\n\nWhy yet another TOML parser? Well, the ecosystem of TOML parsers in JavaScript is quite underwhelming, most likely due\nto a lack of interest. With most parsers being outdated, unmaintained, non-compliant, or a combination of these, a new\nparser didn't feel too out of place.\n\n*[insert xkcd 927]*\n\nsmol-toml passes most of the tests from [BurntSushi's `toml-test` suite](https://github.com/BurntSushi/toml-test).\nHowever, due to the nature of JavaScript and the limits of the language, it doesn't pass certain tests, namely:\n- Invalid UTF-8 strings are not rejected\n- Certain invalid UTF-8 codepoints are not rejected\n- smol-toml doesn't preserve type information between integers and floats (in JS, everything is a float)\n- smol-toml doesn't support the whole 64-bit range for integers (but does throw an appropriate error)\n  - As all numbers are floats in JS, the safe range is `2**53 - 1` <=> `-(2**53 - 1)`.\n\nsmol-toml also passes all of the tests in https://github.com/iarna/toml-spec-tests.\n\n<details>\n<summary>List of failed `toml-test` cases</summary>\n\nThese tests were done by modifying `primitive.ts` and make the implementation return bigints for integers. This allows\nverifying the parser correctly intents a number to be an integer or a float.\n\n*Ideally, this becomes an option of the library, but for now...*\n\nThe following parse tests are failing:\n- invalid/encoding/bad-utf8-in-comment\n- invalid/encoding/bad-utf8-in-multiline-literal\n- invalid/encoding/bad-utf8-in-multiline\n- invalid/encoding/bad-utf8-in-string-literal\n- invalid/encoding/bad-utf8-in-string\n- invalid/string/bad-codepoint\n</details>\n\n## Installation\n```\n[pnpm | yarn | npm] i smol-toml\n```\n\n## Usage\n```js\nimport { parse, stringify } from 'smol-toml'\n\nconst doc = '...'\nconst parsed = parse(doc)\nconsole.log(parsed)\n\nconst toml = stringify(parsed)\nconsole.log(toml)\n```\n\nA few notes on the `stringify` function:\n- `undefined` and `null` values on objects are ignored (does not produce a key/value).\n- `undefined` and `null` values in arrays are **rejected**.\n- Functions, classes and symbols are **rejected**.\n- floats will be serialized as integers if they don't have a decimal part.\n  - `stringify(parse('a = 1.0')) === 'a = 1'`\n- JS `Date` will be serialized as Offset Date Time\n  - Use the [`TomlDate` object](#dates) for representing other types.\n\n### Dates\n`smol-toml` uses an extended `Date` object to represent all types of TOML Dates. In the future, `smol-toml` will use\nobjects from the Temporal proposal, but for now we're stuck with the legacy Date object.\n\n```js\nimport { TomlDate } from 'smol-toml'\n\n// Offset Date Time\nconst date = new TomlDate('1979-05-27T07:32:00.000-08:00')\nconsole.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, false\nconsole.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000-08:00\n\n// Local Date Time\nconst date = new TomlDate('1979-05-27T07:32:00.000')\nconsole.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> true, false, false, true\nconsole.log(date.toISOString()) // ~> 1979-05-27T07:32:00.000\n\n// Local Date\nconst date = new TomlDate('1979-05-27')\nconsole.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, true, false, true\nconsole.log(date.toISOString()) // ~> 1979-05-27\n\n// Local Time\nconst date = new TomlDate('07:32:00')\nconsole.log(date.isDateTime(), date.isDate(), date.isTime(), date.isLocal()) // ~> false, false, true, true\nconsole.log(date.toISOString()) // ~> 07:32:00.000\n```\n\nYou can also wrap a native `Date` object and specify using different methods depending on the type of date you wish\nto represent:\n\n```js\nimport { TomlDate } from 'smol-toml'\n\nconst jsDate = new Date()\n\nconst offsetDateTime = TomlDate.wrapAsOffsetDateTime(jsDate)\nconst localDateTime = TomlDate.wrapAsLocalDateTime(jsDate)\nconst localDate = TomlDate.wrapAsLocalDate(jsDate)\nconst localTime = TomlDate.wrapAsLocalTime(jsDate)\n```\n\n## Performance\nA note on these performance numbers: in some highly synthetic tests, other parsers such as `fast-toml` greatly\noutperform other parsers, mostly due to their lack of compliance with the spec. For example, to parse a string,\n`fast-toml` skips the entire string while `smol-toml` does validate the string, costing a fair chair of performance.\n\nThe ~5MB test file used for benchmark here is filled with random data which attempts to be close-ish to reality. The\nidea is to have a file relatively close to a real-world application.\n\nThe large TOML generator can be found [here](https://gist.github.com/cyyynthia/e77c744cb6494dabe37d0182506526b9)\n\n| **Parse**      | smol-toml           | @iarna/toml@3.0.0 | @ltd/j-toml     | fast-toml       |\n|----------------|---------------------|-------------------|-----------------|-----------------|\n| Spec example   | **71,356.51 op/s**  | 33,629.31 op/s    | 16,433.86 op/s  | 29,421.60 op/s  |\n| ~5MB test file | **3.8091 op/s**     | *DNF*             | 2.4369 op/s     | 2.6078 op/s     |\n\n| **Stringify**  | smol-toml            | @iarna/toml@3.0.0 | @ltd/j-toml    |\n|----------------|----------------------|-------------------|----------------|\n| Spec example   | **195,191.99 op/s**  | 46,583.07 op/s    | 5,670.12 op/s  |\n| ~5MB test file | **14.6709 op/s**     | 3.5941 op/s       | 0.7856 op/s    |\n\n<details>\n<summary>Detailed benchmark data</summary>\n\nTests ran using Vitest v0.31.0 on commit f58cb6152e667e9cea09f31c93d90652e3b82bf5\n\nCPU: Intel Core i7 7700K (4.2GHz)\n\n```\n RUN  v0.31.0\n\n ✓ bench/parseSpecExample.bench.ts (4) 2462ms\n     name                hz     min     max    mean     p75     p99    p995    p999     rme  samples\n   · smol-toml    71,356.51  0.0132  0.2633  0.0140  0.0137  0.0219  0.0266  0.1135  ±0.37%    35679   fastest\n   · @iarna/toml  33,629.31  0.0272  0.2629  0.0297  0.0287  0.0571  0.0650  0.1593  ±0.45%    16815\n   · @ltd/j-toml  16,433.86  0.0523  1.3088  0.0608  0.0550  0.1140  0.1525  0.7348  ±1.47%     8217   slowest\n   · fast-toml    29,421.60  0.0305  0.2995  0.0340  0.0312  0.0618  0.0640  0.1553  ±0.47%    14711\n ✓ bench/parseLargeMixed.bench.ts (3) 16062ms\n     name             hz     min     max    mean     p75     p99    p995    p999     rme  samples\n   · smol-toml    3.8091  239.60  287.30  262.53  274.17  287.30  287.30  287.30  ±3.66%       10   fastest\n   · @ltd/j-toml  2.4369  376.73  493.49  410.35  442.58  493.49  493.49  493.49  ±7.08%       10   slowest\n   · fast-toml    2.6078  373.88  412.79  383.47  388.62  412.79  412.79  412.79  ±2.72%       10\n ✓ bench/stringifySpecExample.bench.ts (3) 1886ms\n     name                 hz     min     max    mean     p75     p99    p995    p999     rme  samples\n   · smol-toml    195,191.99  0.0047  0.2704  0.0051  0.0050  0.0099  0.0110  0.0152  ±0.41%    97596   fastest\n   · @iarna/toml   46,583.07  0.0197  0.2808  0.0215  0.0208  0.0448  0.0470  0.1704  ±0.47%    23292\n   · @ltd/j-toml    5,670.12  0.1613  0.5768  0.1764  0.1726  0.3036  0.3129  0.4324  ±0.56%     2836   slowest\n ✓ bench/stringifyLargeMixed.bench.ts (3) 24057ms\n     name              hz       min       max      mean       p75       p99      p995      p999     rme  samples\n   · smol-toml    14.6709   65.1071   79.2199   68.1623   67.1088   79.2199   79.2199   79.2199  ±5.25%       10   fastest\n   · @iarna/toml   3.5941    266.48    295.24    278.24    290.10    295.24    295.24    295.24  ±2.83%       10\n   · @ltd/j-toml   0.7856  1,254.33  1,322.05  1,272.87  1,286.82  1,322.05  1,322.05  1,322.05  ±1.37%       10   slowest\n\n\n BENCH  Summary\n\n  smol-toml - bench/parseLargeMixed.bench.ts >\n    1.46x faster than fast-toml\n    1.56x faster than @ltd/j-toml\n\n  smol-toml - bench/parseSpecExample.bench.ts >\n    2.12x faster than @iarna/toml\n    2.43x faster than fast-toml\n    4.34x faster than @ltd/j-toml\n\n  smol-toml - bench/stringifyLargeMixed.bench.ts >\n    4.00x faster than @iarna/toml\n    18.33x faster than @ltd/j-toml\n\n  smol-toml - bench/stringifySpecExample.bench.ts >\n    4.19x faster than @iarna/toml\n    34.42x faster than @ltd/j-toml\n```\n\n---\nAdditional notes:\n\nI initially tried to benchmark `toml-nodejs`, but the 0.3.0 package is broken.\nI initially reported this to the library author, but the author decided to\n- a) advise to use a custom loader (via *experimental* flag) to circumvent the invalid imports.\n  - Said flag, `--experimental-specifier-resolution`, has been removed in Node v20.\n- b) [delete the issue](https://github.com/huan231/toml-nodejs/issues/12) when pointed out links to the NodeJS\ndocumentation about the flag removal and standard resolution algorithm.\n\nFor the reference anyways, `toml-nodejs` (with proper imports) is ~8x slower on both parse benchmark with:\n- spec example: 7,543.47 op/s\n- 5mb mixed: 0.7006 op/s\n</details>\n","readmeFilename":"README.md"}