{"id":17251071,"url":"https://github.com/fumieval/winery","last_synced_at":"2025-04-10T02:25:51.486Z","repository":{"id":56882583,"uuid":"130475592","full_name":"fumieval/winery","owner":"fumieval","description":"Preservative serialisation format","archived":false,"fork":false,"pushed_at":"2023-07-18T09:46:33.000Z","size":1192,"stargazers_count":89,"open_issues_count":3,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-26T10:46:05.850Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fumieval.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","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}},"created_at":"2018-04-21T13:20:47.000Z","updated_at":"2024-01-04T11:02:49.000Z","dependencies_parsed_at":"2024-02-26T01:34:56.696Z","dependency_job_id":"3a356fe8-0da9-49db-8bc2-52e835905743","html_url":"https://github.com/fumieval/winery","commit_stats":{"total_commits":305,"total_committers":4,"mean_commits":76.25,"dds":"0.016393442622950838","last_synced_commit":"4203c48d42215e3eaa9bef98ac8910942dffa0c9"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumieval%2Fwinery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumieval%2Fwinery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumieval%2Fwinery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fumieval%2Fwinery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fumieval","download_url":"https://codeload.github.com/fumieval/winery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143663,"owners_count":21054817,"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":"2024-10-15T06:50:16.405Z","updated_at":"2025-04-10T02:25:51.424Z","avatar_url":"https://github.com/fumieval.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# winery\n\n![logo](https://github.com/fumieval/winery/blob/master/art/logo256px.png?raw=true)\n![Haskell CI](https://github.com/fumieval/winery/workflows/Haskell%20CI/badge.svg)\n[![Hackage](https://img.shields.io/hackage/v/winery.svg)](https://hackage.haskell.org/package/winery)\n[![Discord](https://img.shields.io/discord/664807830116892674?color=%237095ec\u0026label=Discord\u0026style=plastic)](https://discord.gg/DG93Tgs)\n\nwinery is a serialisation library focusing on __performance__, __compactness__\nand __compatibility__. The primary feature is that metadata (types, field names,\netc) are packed into one schema.\n\nA number of formats, like JSON and CBOR, attach metadata for each value:\n\n`[{\"id\": 0, \"name\": \"Alice\"}, {\"id\": 1, \"name\": \"Bob\"}]`\n\nIn contrast, winery stores them separately, eliminating redundancy while\nguaranteeing well-typedness:\n\n```\n0402 0402 0269 6410 046e 616d 6514  [{ id :: Integer, name :: Text }]\n0200 0541 6c69 6365 0103 426f 62    [(0, \"Alice\"), (1, \"Bob\")]\n```\n\nUnlike other libraries that don't preserve metadata (e.g.` binary`, `cereal`, `store`) at all, winery also\nallows readers to decode values regardless of the current implementation.\n\n## Interface\n\nThe interface is simple; `serialise` encodes a value with its schema, and\n`deserialise` decodes a ByteString using the schema in it.\n\n```haskell\nclass Serialise a where\n  schema :: Serialise a =\u003e proxy a -\u003e Schema\n\nserialise :: Serialise a =\u003e a -\u003e B.ByteString\ndeserialise :: Serialise a =\u003e B.ByteString -\u003e Either WineryException a\n```\n\nIt's also possible to serialise schemata and data separately. `serialiseSchema`\nencodes a schema and its version number into a ByteString, and\n`serialiseOnly` serialises a value without a schema.\n\n```haskell\nserialiseSchema :: Schema -\u003e B.ByteString\nserialiseOnly :: Serialise a =\u003e a -\u003e B.ByteString\n```\n\nIn order to decode data generated this way, pass the result of `deserialiseSchema`\nto `getDecoder`. Finally run `evalDecoder` to deserialise them.\n\n```haskell\ndeserialiseSchema :: B.ByteString -\u003e Either WineryException Schema\ngetDecoder :: Serialise a =\u003e Schema -\u003e Either WineryException (Decoder a)\nevalDecoder :: Decoder a -\u003e B.ByteString -\u003e a\n```\n\n## Deriving an instance\n\nThe recommended way to create an instance of `Serialise` is to use `DerivingVia`.\n\n```haskell\n  deriving Generic\n  deriving Serialise via WineryRecord Foo\n```\n\nfor single-constructor records, or just\n\n```haskell\n  deriving Generic\n  deriving Serialise via WineryVariant Foo\n```\n\nfor any ADT. The former explicitly describes field names in the schema, and the\nlatter does constructor names.\n\nIf you want to customise one of the methods, you can use `bundleVia` to supply the rest of definitions.\n\n```haskell\ninstance Serialise Foo where\n  bundleSerialise = bundleVia WineryRecord\n  extractor = buildExtractor $ Foo\n    \u003c$\u003e extractField \"foo\"\n    \u003c*\u003e extractField \"bar\"\n```\n\n## Backward compatibility\n\nIf the representation is not the same as the current version (i.e. the schema\n is different), the data cannot be decoded directly. This is where extractors\ncome in.\n\n`Extractor` parses a schema and returns a function which gives a value back from\na `Term`.\n\nYou can build an extractor using combinators such as `extractField`.\n\nIf you want to customise an extractor for a variant, the pair of `gvariantExtractors` and `buildVariantExtractors` is handy.\n\n```haskell\ngvariantExtractors :: (GSerialiseVariant (Rep a), Generic a) =\u003e HM.HashMap T.Text (Extractor a)\nbuildVariantExtractor :: (Generic a, Typeable a) =\u003e HM.HashMap T.Text (Extractor a) -\u003e Extractor a\n```\n\n`Extractor` is Alternative, meaning that multiple extractors (such as a default\ngeneric implementation and fallback plans) can be combined into one.\n\nAltering an instance for a record type is a little bit tricky.\nHKD can represent a record where each field is `Subextractor` instead of the orignal type.\nThe [barbies-th](http://hackage.haskell.org/package/barbies-th) allows us to derive it from a plain declaration.\n\n```haskell\nimport Barbies.Bare\nimport Barbies.TH\n\ndeclareBareB [d|\n  data HRecB = HRec\n    { baz :: !Int\n    , qux :: !Text\n    }\n    |]\ntype HRec = HRecB Bare Identity\n```\n\nObtain a record of extractors using `bextractors :: forall b. (AllB Serialise b, ...) =\u003e b Subextractor`, update it as necessary,\nthen build an extractor for an entire record by `buildRecordExtractor`.\n\n```haskell\ninstance Serialise HRec where\n  bundleSerialise = bundleVia WineryRecord\n  extractor = fmap bstrip $ buildRecordExtractor bextractors\n    { qux = extractField \"qux\" \u003c|\u003e extractField \"oldQux\" }\n```\n\nMore generic instance (for covered types) can be defined as below:\n\n```haskell\ninstance (Typeable h, AllBF Serialise h (HRecB Covered)) =\u003e Serialise (HRecB Covered h) where\n  bundleSerialise = bundleVia Barbie\n  extractor = buildRecordExtractorF bextractorsF\n    { qux = Compose $ extractField \"qux\" \u003c|\u003e extractField \"oldQux\" }\n```\n\n## Pretty-printing\n\n`Term` can be deserialised from any winery data. It can be pretty-printed using the `Pretty` instance:\n\n```\n{ bar: \"hello\"\n, baz: 3.141592653589793\n, foo: Just 42\n}\n```\n\nYou can use the `winery` command-line tool to inspect values.\n\n```\n$ winery '.[:10] | .first_name .last_name' benchmarks/data.winery\nShane Plett\nMata Snead\nLevon Sammes\nIrina Gourlay\nBrooks Titlow\nAntons Culleton\nRegine Emerton\nStarlin Laying\nOrv Kempshall\nElizabeth Joseff\nCathee Eberz\n```\n\nAt the moment, the following queries are supported:\n\n* `.` return itself\n* `.[]` enumerate all the elements in a list\n* `.[i]` get the i-th element\n* `.[i:j]` enumerate i-th to j-th items\n* `.N` n-th element of a product\n* `.foo` Get a field named `foo`\n* `F | G` compose queries (left to right)\n\n## Performance\n\nA useful library should also be fast. Benchmarking encoding/decoding of the\nfollowing datatype.\n\n```haskell\ndata Gender = Male | Female\n\ndata TestRec = TestRec\n  { id_ :: !Int\n  , first_name :: !Text\n  , last_name :: !Text\n  , email :: !Text\n  , gender :: !Gender\n  , num :: !Int\n  , latitude :: !Double\n  , longitude :: !Double\n  }\n```\n\nHere's the result:\n\n|           | encode 1 | encode 1000 | decode  | length  |\n|-----------|----------|-------------|---------| ------- |\n| winery    | __0.28 μs__  | __0.26 ms__ | __0.81 ms__ | __58662__ |\n| cereal    | 0.82 μs  | 0.78 ms     | 0.90 ms | 91709  |\n| binary    | 1.7 μs   | 1.7 ms      | 2.0 ms  | 125709 |\n| serialise | 0.61 μs  | 0.50 ms     | 1.4 ms  | 65437  |\n| store     | 54 ns    | 56 μs       | 0.13 ms | 126410 |\n| aeson     | 9.9 μs   | 9.7 ms      | 17 ms   | 160558 |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffumieval%2Fwinery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffumieval%2Fwinery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffumieval%2Fwinery/lists"}