{"id":17452370,"url":"https://github.com/omar-azmi/fbicodec_ts","last_synced_at":"2026-04-28T11:34:27.647Z","repository":{"id":221218317,"uuid":"753740065","full_name":"omar-azmi/fbicodec_ts","owner":"omar-azmi","description":"A Forward and Backward Invertible binary serializer TypeScript library built on modularity and composition.  When you hear the words `FBI OPEN UP!`, you'll be able to prove your innocence with any data encoded with this library.","archived":false,"fork":false,"pushed_at":"2024-03-26T12:54:10.000Z","size":250,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-20T09:01:41.205Z","etag":null,"topics":["binary-serialization","codec","decoder","deno","encoder","es6","file-parser","invertible","modular","oop","parser","schema","serialization","serialization-library","tiny","typescript","unparser","unserialize"],"latest_commit_sha":null,"homepage":"https://omar-azmi.github.io/fbicodec_ts/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omar-azmi.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":".github/code_of_conduct.md","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":"2024-02-06T17:49:53.000Z","updated_at":"2024-02-19T20:06:52.000Z","dependencies_parsed_at":"2024-03-26T14:02:32.624Z","dependency_job_id":null,"html_url":"https://github.com/omar-azmi/fbicodec_ts","commit_stats":null,"previous_names":["omar-azmi/fbicodec_ts"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-azmi%2Ffbicodec_ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-azmi%2Ffbicodec_ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-azmi%2Ffbicodec_ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar-azmi%2Ffbicodec_ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omar-azmi","download_url":"https://codeload.github.com/omar-azmi/fbicodec_ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245971923,"owners_count":20702705,"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":["binary-serialization","codec","decoder","deno","encoder","es6","file-parser","invertible","modular","oop","parser","schema","serialization","serialization-library","tiny","typescript","unparser","unserialize"],"created_at":"2024-10-17T23:06:14.129Z","updated_at":"2026-04-28T11:34:22.607Z","avatar_url":"https://github.com/omar-azmi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FBIcodec\n\nFBIcodec is so cleanly invertible, it's the last thing the FBI would investigate!\n\nThis is a typescript library for building bidirectional (encoding and decoding) codecs using composable steps.\nThe \"FBI\" part in the name stands for \"Forward-Backward-Interfaced\", and Codec stands for an invertible data transformation.\n\nThe main building block of the library is its general purpose `Step` interface, which ensures the ability for a forward transformation to be reversed.\nThe forward and backward methods take a single argument, allowing Steps to be composed into more complex Codecs.\n\n\n### Features\n\n- Composable steps for encoding and decoding binary data\n- Steps for primitive types like numbers, strings, bytes\n- Steps for composing records, arrays, sequences\n- Invertible - encoding and decoding are symmetric\n- Type safe\n\n\n### Overview\n\nThe main abstractions are:\n- `Step` - encodes `forward` and decodes `backward` between a source and target type.\n- `Binarystep` - a `Step` for encoding/decoding binary data.\n\nTo work with binary data of primitive types, such as: numbers, strings, bytes etc..., you can use the the `BinaryPureStep`s inside the file [`binary_primitive_steps.ts`](/src/binary_primitive_steps.ts).\n- `BinaryNumberStep` - supports signed/unsigned integers of 8, 16, 32 and 64 bits, and floats of 32 and 64 bits, in both little-endian and big-endian formats.\n- `BinaryStringStep` - for strings with varying lengths (based on the `args.length` parameter).\n- `BinaryCStringStep` - for NUL (`\"\\x00\"`) terminated strings.\n- `BinaryBytesStep` - for sequence of bytes (based on the `args.length` parameter).\n- `BinaryNumberArrayStep` - for numeric array of numbers (based on the `args.length` parameter).\n\nTo work with binary data of composite types, such as: records, arrays, sequences etc..., you can use the the `BinaryPureStep`s inside the file [`binary_composition_steps`](/src/binary_composition_steps.ts).\n- `BinaryRecordStep` - encodes a record with named fields, when provided with a sequence of `Steps` for each field.\n- `BinaryArrayStep` - encodes an array of items, when provided with a single `Step` for the item type.\n- `SequentialSteps` - chains multiple `Step`s.\n\n\nFor example, here is a step that decode and then repack PNG image file's metadata blocks:\n```ts\nclass PNG_Codec_Step extends PureStep\u003cUint8Array, GeneralChunk_schema[]\u003e {\n\tforward(input: Uint8Array): GeneralChunk_schema[] {\n\t\t// parse input into chunks\n\t}\n\tbackward(input: GeneralChunk_schema[]): Uint8Array {\n\t\t// encode chunks into binary\n\t}\n}\n```\n\n\n## Theory\n\nThe key components that enable building robust bidirectional transformations are:\n\n- `Step\u003cFROM, TO, LOST\u003e`\n  - Defines symmetric forward and backward methods between source `FROM` and target `TO` types.\n  Any lost information should be stored in the `LOST` private property.\n\n- `PureStep\u003cFROM, TO\u003e extends Step\u003cFROM, TO, never\u003e`\n  - This is a `Step` that is guaranteed to not lose information during forward transformation, allowing backward transformation to fully reconstruct the original value.\nIt also means that one may reuse a single instance of this kind of step for multiple forward and backward transformations, in whatever order it is deemed convenient.\nHence, these kind of steps are suitable for being applied repeatdly by larger compositional steps.\n\n- `BinaryStep\u003cOUT, ARGS, LOST\u003e extends Step\u003c{ bin: Uint8Array, pos: number, args: ARGS }, { val: OUT, len: number }, LOST\u003e`\n  - A step that specialized for parsing binary data.\nbackward encodes the wrapped `OUT` value back into a wrapped `Uint8Array` object.\n\n- `BinaryPureStep\u003cOUT, ARGS\u003e extends PureStep\u003c{ bin: Uint8Array, pos: number, args: ARGS }\u003e`\n  - Similar to `BinaryStep`, but is guaranteed not to lose data during forward transformation.\nThis is the class that is basically used by all implementations of `BinaryStep`s.\n\n\nThese simple interfaces allow `Step`s to be composed in a type-safe way.\n\nMoreover, the compositions form a tree structure that preserves invertibility - as long as each `Step` inside implements their `forward` and `backward` methods correctly, the entire composition will be robustly reversible.\n\nIt also makes diagnosing issues easier - if there is a decoding error, it must be within one of the composed Steps.\nThe composition tree narrows down where the issue lies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomar-azmi%2Ffbicodec_ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomar-azmi%2Ffbicodec_ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomar-azmi%2Ffbicodec_ts/lists"}