{"_id":"@biubiupiu/fractional-indexing","name":"@biubiupiu/fractional-indexing","dist-tags":{"latest":"0.0.1-alpha.0"},"versions":{"0.0.1-alpha.0":{"name":"@biubiupiu/fractional-indexing","version":"0.0.1-alpha.0","private":false,"description":"Provides functions for generating ordering strings","main":"src/index.js","engines":{"node":"^14.13.1 || >=16.0.0"},"scripts":{"build-dts":"rm -f src/*.d.ts && tsc --emitDeclarationOnly && prettier src/*.d.ts --write","build":"npm run build-dts","format":"prettier *.json src/ --write","prepare":"npm run build && npm run format","prepack":"npm run prepare","test":"node src/test.js"},"keywords":["fractional","indexing","ordering","order"],"homepage":"https://github.com/rocicorp/fractional-indexing#readme","repository":{"type":"git","url":"git+https://github.com/rocicorp/fractional-indexing.git"},"bugs":{"url":"https://github.com/rocicorp/fractional-indexing/issues"},"author":{"name":"arv@rocicorp.dev"},"license":"CC0-1.0","devDependencies":{"prettier":"^2.6.0","typescript":"^4.6.2"},"publishConfig":{"access":"public"},"_id":"@biubiupiu/fractional-indexing@0.0.1-alpha.0","gitHead":"40a355ecd030f3e4ff25db419b7d7955e59af4e5","types":"./src/index.d.ts","_nodeVersion":"20.11.1","_npmVersion":"10.2.4","dist":{"integrity":"sha512-jO6ak7LCQORcWslJe9h6Q57t2JtC827vNszfQEnR1KhxL2cz0Onjcrq8JJi3f4c4LITCFxypUMLVaMeGc0zNhQ==","shasum":"e3326d4952bb89c7e368c3927d088de18b2b557a","tarball":"https://registry.npmjs.org/@biubiupiu/fractional-indexing/-/fractional-indexing-0.0.1-alpha.0.tgz","fileCount":5,"unpackedSize":21380,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFPJ0xkAfhCNqb5hqTugMLeeg5q6ZTqFMdt8qqoT/WTdAiEAldyluk4k4BpWvRkVh6DNp0JL5hMPgN1eYiG0oP+7u98="}]},"_npmUser":{"name":"biubiupiu","email":"biubiupiu_email@qq.com"},"directories":{},"maintainers":[{"name":"biubiupiu","email":"biubiupiu_email@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fractional-indexing_0.0.1-alpha.0_1764749224610_0.0414393697124138"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-03T08:07:04.537Z","0.0.1-alpha.0":"2025-12-03T08:07:04.800Z","modified":"2025-12-03T08:07:05.155Z"},"maintainers":[{"name":"biubiupiu","email":"biubiupiu_email@qq.com"}],"description":"Provides functions for generating ordering strings","homepage":"https://github.com/rocicorp/fractional-indexing#readme","keywords":["fractional","indexing","ordering","order"],"repository":{"type":"git","url":"git+https://github.com/rocicorp/fractional-indexing.git"},"author":{"name":"arv@rocicorp.dev"},"bugs":{"url":"https://github.com/rocicorp/fractional-indexing/issues"},"license":"CC0-1.0","readme":"# Fractional Indexing\n\nThis is based on [Implementing Fractional Indexing\n](https://observablehq.com/@dgreensp/implementing-fractional-indexing) by [David Greenspan\n](https://github.com/dgreensp).\n\nFractional indexing is a technique to create an ordering that can be used for [Realtime Editing of Ordered Sequences](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/).\n\nThis implementation includes variable-length integers, and the prepend/append optimization described in David's article.\n\n## API\n\n### `generateKeyBetween`\n\nGenerate a single key in between two points.\n\n```ts\ngenerateKeyBetween(\n  a: string | null | undefined, // start\n  b: string | null | undefined, // end\n  digits?: string | undefined = BASE_62_DIGITS, // optional character encoding\n): string;\n```\n\n```ts\nimport { generateKeyBetween } from 'fractional-indexing';\n\nconst first = generateKeyBetween(null, null); // \"a0\"\n\n// Insert after 1st\nconst second = generateKeyBetween(first, null); // \"a1\"\n\n// Insert after 2nd\nconst third = generateKeyBetween(second, null); // \"a2\"\n\n// Insert before 1st\nconst zeroth = generateKeyBetween(null, first); // \"Zz\"\n\n// Insert in between 2nd and 3rd (midpoint)\nconst secondAndHalf = generateKeyBetween(second, third); // \"a1V\"\n```\n\n### `generateNKeysBetween`\n\nUse this when generating multiple keys at some known position, as it spaces out indexes more evenly and leads to shorter keys.\n\n```ts\ngenerateNKeysBetween(\n  a: string | null | undefined, // start\n  b: string | null | undefined, // end\n  n: number // number of keys to generate evenly between start and end\n  digits?: string | undefined = BASE_62_DIGITS, // optional character encoding\n): string[];\n```\n\n```ts\nimport { generateNKeysBetween } from 'fractional-indexing';\n\nconst first = generateNKeysBetween(null, null, 2); // ['a0', 'a1']\n\n// Insert two keys after 2nd\ngenerateNKeysBetween(first[1], null, 2); // ['a2', 'a3']\n\n// Insert two keys before 1st\ngenerateNKeysBetween(null, first[0], 2); // ['Zy', 'Zz']\n\n// Insert two keys in between 1st and 2nd (midpoints)\ngenerateNKeysBetween(second, third, 2); // ['a0G', 'a0V']\n```\n\n## Sorting\n\nThe indexes generated by this library are case-sensitive. While [`Array.prototype.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) will [work out of the box](https://github.com/rocicorp/fractional-indexing/issues/19), note that [`String.prototype.localCompare`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) works case-insensitively and will [give an incorrect ordering](https://github.com/rocicorp/fractional-indexing/issues/20) if used as a sort predicate. Instead, use native string comparison:\n\n```js\nconst arr = [\n  {\n    id: \"todo_1253241\",\n    content: \"Read the docs\",\n    fractionalIndex: \"YzZ\"\n  },\n  {\n    id: \"todo_8973942\",\n    content: \"Open a PR\",\n    fractionalIndex: \"Yza\" \n  }\n]\nconst sorted = arr.toSorted((a, b) =>\n  a.fractionalIndex < b.fractionalIndex\n    ? -1\n    : a.fractionalIndex > b.fractionalIndex\n      ? 1\n      : 0,\n);\n```\n\n## Other Implementations\n\n### Languages\n\nThese libraries should be byte-for-byte compatible.\n\n| Language | Repo                                                  |\n| -------- | ----------------------------------------------------- |\n| Go       | https://github.com/rocicorp/fracdex                   |\n| Python   | https://github.com/httpie/fractional-indexing-python  |\n| Kotlin   | https://github.com/darvelo/fractional-indexing-kotlin |\n| Ruby     | https://github.com/kazu-2020/fractional_indexer       |\n\n### Random Jitter\n\nTo minimize the likelihood of index collisions when generating fractional indexes concurrently, [random jitter](https://madebyevan.com/algos/crdt-fractional-indexing/) can be added to the generated indices. These libraries extend this package's functionality with random jitter.\n\n| Language   | Repo                                                         |\n| ---------- | ------------------------------------------------------------ |\n| TypeScript | https://github.com/nathanhleung/jittered-fractional-indexing |\n\n","readmeFilename":"README.md","_rev":"1-e07e0e4587851402828b1def0d681f17"}