{"id":28066756,"url":"https://github.com/gorhill/s14e-serializer","last_synced_at":"2025-05-12T15:52:27.618Z","repository":{"id":269895186,"uuid":"908793790","full_name":"gorhill/s14e-serializer","owner":"gorhill","description":"A library to de/serialize structured-cloneable data to a Unicode string, optionally with LZ4 compression","archived":false,"fork":false,"pushed_at":"2024-12-28T14:24:18.000Z","size":36,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-10T16:49:03.199Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gorhill.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-27T01:44:16.000Z","updated_at":"2025-04-23T08:30:10.000Z","dependencies_parsed_at":"2025-02-12T03:45:29.369Z","dependency_job_id":null,"html_url":"https://github.com/gorhill/s14e-serializer","commit_stats":null,"previous_names":["gorhill/s14e-serializer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhill%2Fs14e-serializer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhill%2Fs14e-serializer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhill%2Fs14e-serializer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gorhill%2Fs14e-serializer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gorhill","download_url":"https://codeload.github.com/gorhill/s14e-serializer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253769048,"owners_count":21961470,"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":[],"created_at":"2025-05-12T15:52:26.301Z","updated_at":"2025-05-12T15:52:27.583Z","avatar_url":"https://github.com/gorhill.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Badge NPM]][NPM]\n\n## Structured-Cloneable to Unicode-Only serializer/deserializer\n\nSerialize/deserialize JavaScript data to/from well-formed Unicode strings.\n\nThe resulting string is meant to be small. As a result, it is not\nhuman-readable, though it contains only printable ASCII characters -- and\npossibly Unicode characters beyond ASCII.\n\nThe resulting JS string will not contain characters which require escaping\nshould it be converted to a JSON value. However it may contain characters which\nrequire escaping should it be converted to a URI component.\n\nNote: strings are serialized as is, so if they contain non-printable ASCII\ncharacters or characters which requires escaping, then the result of the\nserialization will reflect this.\n\nCharacteristics:\n\n- Serializes/deserializes data to/from a single well-formed Unicode string\n- Strings do not require escaping, i.e. they are stored as-is\n- Supports multiple references to same object\n- Supports reference cycles\n- Supports synchronous and asynchronous API\n- Optionally supports LZ4 compression\n\n### Motivation\n\nThe browser does not expose an API to serialize structured-cloneable types into\na single string. `JSON.stringify()` does not support complex JavaScript objects,\nand does not support references to composite types. Unless the data to serialize\nis only JS strings, it is difficult to easily switch from one type of storage to\nanother.\n\nSerializing to a well-formed Unicode string allows to store structured-cloneable\ndata to any storage. Not all storages support storing binary data, but all\nstorages support storing Unicode strings.\n\nData types      | String           | JSONable         | structured-cloneable\n--------------- | ---------------- | ---------------- | ---------------------\ndocument.cookie | Yes              | No               | No\nlocalStorage    | Yes              | No               | No\nIndexedDB       | Yes              | Yes              | Yes\nbrowser.storage | Yes              | Yes              | No\nCache API       | Yes              | No               | No\n\nThe above table shows that only JS strings can be persisted natively to all\ntypes of storage. The purpose of this library is to convert structure-cloneable\ndata (which is a superset of JSONable data) into a single JS string.\n\n### Usage\n\nSee [test/test.js](./test/test.js) for typical usage.\n\n#### In Node.js:\n\n```js\nimport { serialize } from '@gorhill/s14e-serializer';\n\n// ...\n\n// Serialize data into string\nconst s1 = serialize(data1);\n\n// Serialize and compress data into string\nconst s2 = serialize(data2, { compress: true });\n\n// Write strings to some storage\n\n// ...\n```\n\n```js\nimport { deserialize } from '@gorhill/s14e-serializer';\n\n// Read strings from some storage\n\n// ...\n\n// Restore data from string\nconst data1 = deserialize(s1);\n\n// Restore data from string\nconst data2 = deserialize(s2);\n\n// ...\n```\n\n#### In browser\n\nCopy `s14e-serializer.js` into your project, then:\n\n```js\nimport {\n    deserialize,\n    deserializeAsync,\n    serialize,\n    serializeAsync,\n} from './s14e-serializer.js';\n\n// ...\n```\n\n### Serializable types\n\n- literals\n    - array\n    - bigint\n    - boolean\n    - number\n    - object\n    - regex\n    - string\n- `null`\n- `undefined`\n- `ArrayBuffer`\n- `Boolean`\n- `DataView`\n- `Date`\n- `Map`\n- `Number`\n- `Object`\n- `RegExp`\n- `Set`\n- `String`\n- `TypedArray`\n    - `Int8Array`\n    - `Uint8Array`\n    - `Uint8ClampedArray`\n    - `Int16Array`\n    - `Uint16Array`\n    - `Int32Array`\n    - `Uint32Array`\n    - `Float32Array`\n    - `Float64Array`\n\n### Validation\n\nThe linter should return no errors or warnings:\n\n    npm run lint\n\nThe test suite should not fail:\n\n    npm run test\n\n### Future\n\nPossible improvements:\n\n- Add support for more built-in types\n- Add support for checksums\n- Add support for custom types\n    - If so the name of the library might no longer make sense...\n\nContributions are welcome.\n\n\u003c!-----------------------------------------------------------------------------\u003e\n\n[NPM]: https://www.npmjs.com/package/@gorhill/s14e-serializer\n\n\u003c!----------------------------------[ Badges ]---------------------------------\u003e\n\n[Badge NPM]: https://img.shields.io/npm/v/@gorhill/s14e-serializer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgorhill%2Fs14e-serializer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgorhill%2Fs14e-serializer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgorhill%2Fs14e-serializer/lists"}