{"id":36667777,"url":"https://github.com/jiftechnify/ts-souko","last_synced_at":"2026-01-12T10:36:59.662Z","repository":{"id":42572481,"uuid":"437924123","full_name":"jiftechnify/ts-souko","owner":"jiftechnify","description":"Type-safe Storage wrapper for TypeScript","archived":false,"fork":false,"pushed_at":"2022-03-31T15:29:56.000Z","size":218,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-11T03:27:20.029Z","etag":null,"topics":["storage","strongly-typed","type-safe","typescript","wrapper"],"latest_commit_sha":null,"homepage":"https://jiftechnify.github.io/ts-souko/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jiftechnify.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":"2021-12-13T15:24:10.000Z","updated_at":"2023-07-07T09:55:50.000Z","dependencies_parsed_at":"2022-08-28T15:33:10.923Z","dependency_job_id":null,"html_url":"https://github.com/jiftechnify/ts-souko","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jiftechnify/ts-souko","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiftechnify%2Fts-souko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiftechnify%2Fts-souko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiftechnify%2Fts-souko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiftechnify%2Fts-souko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jiftechnify","download_url":"https://codeload.github.com/jiftechnify/ts-souko/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jiftechnify%2Fts-souko/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["storage","strongly-typed","type-safe","typescript","wrapper"],"created_at":"2026-01-12T10:36:58.350Z","updated_at":"2026-01-12T10:36:59.646Z","avatar_url":"https://github.com/jiftechnify.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ts-souko\n*ts-souko* is a library for constructing **type-safe Storage wrapper**, for TypeScript.\n\n\u003e *souko*(倉庫) is a Japanese word stands for \"warehouse\", or \"storage\".\n\n## Installation\nBy npm:\n\n```\nnpm i ts-souko\n```\n\nBy yarn:\n\n```\nyarn add ts-souko\n```\n\n## Basic Usage\n\n```typescript\nimport { createTypedStorage, codecs, baseStorages } from 'ts-souko';\n\n// Creating typed wrapper for localStorage.\n// For each key, specify the `Codec` for the type of corresponding value.\nconst storage = createTypedStorage({\n  id: codecs.number,\n  name: codecs.string,\n}, { base: baseStorages.webLocal } );\n\n// Now, type of value is inferred as you specify key!\nstorage.set('id', 100);       // OK\nstorage.set('name', 'Alice'); // OK\nstorage.set('id', 'nan');     // type error!\nstorage.set('name', 0);       // type error!\nstorage.set('unknown', null); // type error!\n\nconst i = storage.get('id');      // i: number | null\nconst n = storage.get('name');    // n: string | null\nconst x = storage.get('unknown'); // type error!\n```\n\n## Features\n\n### Type-safety and Developer Experience\n\nUsing *ts-souko*, you can get type-safety on string value storages by minimum code. Moreover, together with VS Code's powerful integration with TypeScript, you can get maximum developer experience on coding using storages. TypeScript compiler will be always on your side!\n\nWith *ts-souko*, you won't be troubled with problems like:\n\n- What keys are available on the storage?\n- What type of value is expected for that key?\n- What type should you convert the value from storage to?\n\n\n\n### Flexibility and Extensibility by Abstractions\n\n*ts-souko* defines 2 abstractions: `BaseStorage` and `Codec`. They make *ts-souko* flexible and extensible.\n\n- `BaseStorage` is abstraction of \"string key - string value\" storage. This enables you to **use** *ts-souko* **on any storage** that has ability to store string value with string key associated, not limited to browser's `localStorage` \nor `sessionStorage`!\n    + \"Async\" version is also supported (`AsyncTypedStorage` on `AsyncBaseStorage`). This is useful to interact with storages that expose async API, such as [React Native Async Storage](https://react-native-async-storage.github.io/async-storage/docs/install/) or [Capacitor Storage](https://capacitorjs.com/docs/apis/storage).\n\n- `Codec\u003cT\u003e` is abstraction about conversion between value of type `T` and it's string representation, back and forth. This enables you to **store and retrieve values of arbitrary type** to/from storage **in arbitrary format**, **with safety**. For example, you can write `Codec` for array of `number`s that converts an array as \"slash(/) separated values\":\n\n```typescript\nimport { codecs, createTypedStorage } from 'ts-souko';\n\n// note: codecs.number implements value-preserving conversion for numbers.\nconst slashSeparatedNumsCodec: Codec\u003cnumber[]\u003e = {\n  encode: (a: number[]): string =\u003e \n    a.map(e =\u003e codecs.number.encode(e)).join('/'),\n\n  decode: (s: string): number[] =\u003e\n    s.split('/').map(e =\u003e codecs.number.decode(e))\n}\n\nconst ts = createTypedStorage({\n  ssv: slashSeparatedNumsCodec, \n}, { ... });\n\nts.set('ssv', [1, 2, 3]) // OK. stores: '1/2/3' \nts.get('ssv')            // =\u003e [1, 2, 3]\n\nts.set('ssv', [\"a\", \"b\"]) // type error!\n```\n\n### Built-in Interoperability with Schema Validation Libraries\n\nVia `Codec` abstraction, you can write code that retrieve value from storage with schema validations using a library like [io-ts](https://gcanti.github.io/io-ts/). Fortunately, you don't have to write own `Codec` with validations! *ts-souko* is equipped with built-in `Codec` interoperate with popular schema validation libraries:\n\n| Library Name | `Codec`  |\n|:-------------|:---------|\n|[io-ts](https://gcanti.github.io/io-ts/) | `codecs.jsonWithIoTs(iotsType, reporter?)`|\n|[superstruct](https://docs.superstructjs.org/)| `codecs.jsonWithSuperstruct(struct)`|\n|[zod](https://github.com/colinhacks/zod#readme)| `codecs.jsonWithZod(zod)` |\n\nExample using *ts-souko* with *io-ts*:\n\n```typescript\nimport { codecs, createTypedStorage } from 'ts-souko';\nimport * as t from 'io-ts';\n\nconst User = t.type({\n  userId: t.number,\n  name: t.string,\n});\ntype User = t.TypeOf\u003ctypeof User\u003e;\n\nconst userCodec = codecs.jsonWithIoTs(User);\nconst ts = crateTypedStorage({\n  user: userCodec,\n}, { ... });\n\nconst u: User = { userId: 1, name: 'Alice' };\nts.set('user', u) // OK\nts.get('user')    // === `u`\n\nts.set('user', { userId: '1', namee: 'Alice' }) // type error, of course.\n```\n\nIf you couldn't find your favorite validation library, you can still use `codecs.jsonWithValidation(validate)`, where `validate` is function implements custom validation logic.\n\n## API Document\nsee [Here](https://jiftechnify.github.io/ts-souko/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiftechnify%2Fts-souko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiftechnify%2Fts-souko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiftechnify%2Fts-souko/lists"}