{"id":14155146,"url":"https://github.com/jasonkuhrt/alge","last_synced_at":"2025-05-16T05:06:20.218Z","repository":{"id":36979116,"uuid":"474513318","full_name":"jasonkuhrt/alge","owner":"jasonkuhrt","description":"Type safe library for creating Algebraic Data Types (ADTs) in TypeScript. 🌱","archived":false,"fork":false,"pushed_at":"2025-05-05T19:43:08.000Z","size":5673,"stargazers_count":120,"open_issues_count":13,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T20:45:01.287Z","etag":null,"topics":["adt","algebraic-data-types","data","typescript"],"latest_commit_sha":null,"homepage":"","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/jasonkuhrt.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,"zenodo":null}},"created_at":"2022-03-27T02:14:31.000Z","updated_at":"2025-02-21T22:01:47.000Z","dependencies_parsed_at":"2025-03-23T19:25:31.862Z","dependency_job_id":"22baa45e-1b5f-4eb5-a8f4-da1debc581b9","html_url":"https://github.com/jasonkuhrt/alge","commit_stats":{"total_commits":367,"total_committers":3,"mean_commits":"122.33333333333333","dds":"0.36239782016348776","last_synced_commit":"25682c6c16f5f28f50628a9922b3824276e01abe"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonkuhrt%2Falge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonkuhrt%2Falge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonkuhrt%2Falge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonkuhrt%2Falge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jasonkuhrt","download_url":"https://codeload.github.com/jasonkuhrt/alge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252576418,"owners_count":21770715,"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":["adt","algebraic-data-types","data","typescript"],"created_at":"2024-08-17T08:02:15.465Z","updated_at":"2025-05-16T05:06:19.963Z","avatar_url":"https://github.com/jasonkuhrt.png","language":"TypeScript","funding_links":[],"categories":["typescript"],"sub_categories":[],"readme":"# alge 🌱\n\n[![trunk](https://github.com/jasonkuhrt/alge/actions/workflows/trunk.yml/badge.svg)](https://github.com/jasonkuhrt/alge/actions/workflows/trunk.yml)\n[![npm version](https://img.shields.io/npm/v/alge.svg)](https://www.npmjs.com/package/alge)\n\n\u003e Hey 👋, FYI here are some other TypeScript-first libraries I've created that might interest you:\n\u003e\n\u003e [`@molt/command`](https://github.com/jasonkuhrt/molt/tree/main/packages/@molt/command) for building simple scripts and command lines.\n\n## TL;DR\n\nLibrary for creating [Algebraic Data Types](https://en.wikipedia.org/wiki/Algebraic_data_type) in TypeScript. Pronounced \"AL GEE\" like [the plant](https://en.wikipedia.org/wiki/Algae) ([or whatever it is](https://www.indefenseofplants.com/blog/2018/2/20/are-algae-plants)). Schemas powered by [Zod](https://github.com/colinhacks/zod) \u003c3.\n\nAn ADT is built like so:\n\n```ts\nimport { Alge } from 'alge'\nimport { z } from 'zod'\n\nconst Length = z.number().positive()\n\n//           o---------- ADT Controller\n//           |            o--------- ADT Builder\nexport const Shape = Alge.data(`Shape`, {\n  Rectangle: {\n    width: Length,\n    height: Length,\n  },\n  Circle: {\n    radius: Length,\n  },\n  Square: {\n    size: Length,\n  },\n})\n```\n\nBuilding an ADT returns a _controller_. Controllers are an API for your data, like constructors and type guards. Constructed data is nothing special, just good old JavaScript POJOs.\n\n```ts\n//    o--------- Member Instance\n//    |        o--------- ADT Controller\n//    |        |     o-------- Member Namespace\n//    |        |     |      o-------- Constructor\n//    |        |     |      |\nconst circle = Shape.Circle.create({ radius: 50 })\n// { _tag: 'Circle', radius: 50 }\n\nconst square = Shape.Square.create({ size: 50 })\n// { _tag: 'Square', size: 5 }\n\nif (Shape.Circle.is(circle)) {\n  console.log(`I Am Circle`)\n}\n\nconst circleForTheOutsideWorld = Shape.Circle.to.json(circle)\n// '{ \"_tag\": \"Circle\", \"radius\": 50 }'\n\nconst squareFromTheOutsideWorld = Shape.Square.from.json({ _tag: 'Square', size: 10 })\n// { _tag: 'Square', size: 10 }\n```\n\nYou can infer the static types from the controller:\n\n```ts\ntype Shape = Alge.infer\u003ctypeof Shape\u003e\n```\n\nYou can pattern match on your constructed data:\n\n```ts\nconst shape = Math.random() \u003e 0.5 ? circle : square\nconst result = Alge.match(shape)\n  .Circle({ radius: 13 }, () =\u003e `Got an unlucky circle!`)\n  .Circle((circle) =\u003e `Got a circle of radius ${circle.radius}!`)\n  .Square({ size: 13 }, () =\u003e `Got an unlucky square!`)\n  .Square((square) =\u003e `Got a square of size ${square.size}!`)\n  .done()\n```\n\nYou can create individual records when you don't need full blown ADTs:\n\n```ts\nimport { Alge } from 'alge'\nimport { z } from 'zod'\n\nconst Circle = Alge.record(`Circle`, { radius: z.number().positive() })\n```\n\nThis is just a taster. Places you can go next:\n\n1. [Install](#installation) and learn interactively (JSDoc is coming soon!)\n1. A formal [features breakdown](#features)\n1. [Code examples](/examples)\n1. A simple [introduction to Algebraic Data Types](#about-algebraic-data-types) (for those unfamiliar)\n1. A [video introduction](https://youtu.be/fLlVQSJx4AU) if you like that format\n\n   [![Video Cover](docs/assets/cover.jpg)](https://youtu.be/JWvy7JXE6vw)\n\n## Contents\n\n\u003c!-- toc --\u003e\n\n- [Installation](#installation)\n- [Roadmap](#roadmap)\n- [Features At a Glance](#features-at-a-glance)\n- [About Algebraic Data Types](#about-algebraic-data-types)\n  - [What?](#what)\n  - [Why?](#why)\n\n* [Features](#features)\n  - [Records](#records)\n    - [Definition (`.record`)](#definition-record)\n    - [Construction (`.create`)](#construction-create)\n    - [Input Defaults](#input-defaults)\n    - [Input Transformation](#input-transformation)\n    - [Input Validation](#input-validation)\n    - [Update](#update)\n    - [Metadata](#metadata)\n    - [Chaining API](#chaining-api)\n    - [Codecs](#codecs)\n      - [Definition (`.codec`)](#definition-codec)\n      - [Usage (`.to.`, `.from`)](#usage-to-from)\n      - [Built In JSON](#built-in-json)\n      - [OrThrow Decoders](#orthrow-decoders)\n  - [Data (Algebraic Data Types)](#data-algebraic-data-types)\n    - [Definition](#definition)\n      - [Referencing Records](#referencing-records)\n      - [Inline Records](#inline-records)\n      - [Referencing Zod Objects](#referencing-zod-objects)\n    - [Construction](#construction)\n    - [Chaining API](#chaining-api-1)\n    - [Identity (`.is`, `.is$`)](#identity-is-is)\n    - [Codecs](#codecs-1)\n      - [Definition (`.codec`)](#definition-codec-1)\n      - [Usage (`to`, `from`)](#usage-to-from)\n  - [Static Types](#static-types)\n    - [Namespaces](#namespaces)\n  - [String Literal Union Pattern Matching](#string-literal-union-pattern-matching)\n    - [Tag Matchers](#tag-matchers)\n    - [Done Versus Else](#done-versus-else)\n  - [ADT Pattern Matching](#adt-pattern-matching)\n    - [Tag Matchers](#tag-matchers-1)\n    - [Value Matchers](#value-matchers)\n    - [Mixing Matchers](#mixing-matchers)\n    - [Done Versus Else](#done-versus-else-1)\n\n\u003c!-- tocstop --\u003e\n\n## Installation\n\n```\nnpm add alge\n```\n\n## Roadmap\n\nThere is no timeline but there are priorities. Refer to the currently three [pinned issues](https://github.com/jasonkuhrt/alge/issues).\n\n## Features At a Glance\n\n- Use a \"builder\" API to define ADTs\n  - Use Zod for schema definition\n  - Define one or more codecs\n- Use the \"controller\" API to work with data\n  - Constructors\n  - Type guards\n  - Built in JSON codec\n  - Automatic ADT level codecs (for codecs common across members)\n- Pattern match on data\n  - Use tag matchers\n  - Use value matchers\n\n## About Algebraic Data Types\n\nAlge is a Type Script library for creating [Algebraic Data Types](https://en.wikipedia.org/wiki/Algebraic_data_type) (ADTs). This guide will take you from not knowing what ADTs are to why you might want to use Alge for them in your code.\n\n### What?\n\nAlgebraic Data Types (ADTs for short) are a methodology of modelling data. They could appear in any context that is about defining and/or navigating the shape of data. One of their fundamental benefits is that they can express different states/inrecords/facts about/of data. They are the combination of two other concepts, _product types_ and _union types_.\n\nA product type is like:\n\n```ts\ninterface Foo {\n  bar: string\n  qux: number\n}\n```\n\nA union type is like:\n\n```ts\ntype Foo = 1 | 2 | 3\n```\n\nBasically, when the power of these two data modelling techniques are combined, we get something far greater than the sum of its parts: ADTs.\n\nADTs can particularly shine at build time. While dynamically typed programing languages (\"scripting language\", e.g. Ruby, JavaScript, Python, ...) can support ADTs at runtime, adding static type support into the mix increases the ADT value proposition. Then there are yet other more minor programing language features like pattern matching that if supporting ADTs make them feel that much more beneficial too.\n\nReferences:\n\n- [Wikipedia entry on ADTs](https://en.wikipedia.org/wiki/Algebraic_data_type)\n- [Type Script documentation on discriminated unions](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions)\n\n### Why?\n\nNow that we have some understanding of _what_ ADTs are let's build some understanding about _why_ we might want to use them. To do this we'll work with an example.\n\nLet's say we want to accept some user input about an npm package dependency version pin. It might come in the form of an exact version or a range of acceptable versions. How would we model this? Let's start without ADTs and then refactor with them to appreciate the difference. Let's assume that input parsing has been taken care of and so here we're only concerned with structured data modelling.\n\n```ts\ninterface Pin {\n  isExact: boolean\n  patch?: number\n  minor?: number\n  major?: number\n  release?: string\n  build?: string\n  range?: Array\u003c{\n    operator: `~` | `\u003e=` | `...` // etc.\n    patch: number\n    minor: number\n    major: number\n    release?: string\n    build?: string\n  }\u003e\n}\n```\n\nThis data modelling is flawed. There is out-of-band information about important data relationships. `release` and `build` are legitimately optional properties but `range` `patch` `minor` `major` all depend on the state of `isExact`. When `true` then `range` is undefined and the others are not, and vice-versa. In other words these configurations of the data are impossible:\n\n```ts\nconst pin = {\n  isExact: true,\n  patch: 1,\n  minor: 2,\n  major: 3,\n  range: [\n    {\n      operator: `~`,\n      patch: 1,\n      minor: 0,\n      major: 0,\n    },\n  ],\n}\n```\n\n```ts\nconst pin = {\n  isExact: false,\n  patch: 1,\n  minor: 2,\n  major: 3,\n}\n```\n\nWhile these are possible:\n\n```ts\nconst pin = {\n  isExact: true,\n  patch: 1,\n  minor: 2,\n  major: 3,\n}\n```\n\n```ts\nconst pin = {\n  isExact: true,\n  patch: 1,\n  minor: 2,\n  major: 3,\n  release: `beta`,\n}\n```\n\n```ts\nconst pin = {\n  isExact: false,\n  range: [\n    {\n      operator: `~`,\n      patch: 1,\n      minor: 0,\n      major: 0,\n    },\n  ],\n}\n```\n\nBut since our data modelling doesn't encode these _facts_ our code suffers. For example:\n\n```ts\nif (pin.isExact) {\n  doSomething(pin.major!)\n  //                       ^\n}\n```\n\nNotice the `!`. Its us telling Type Script that `major` is definitely not undefined and so the type error can be ignored. In JS its even worse, as we wouldn't even be prompted to think about such cases, unless we remember to. Seems trivial in this case, but at scale day after day often with unfamiliar code a mistake will inevitably be made. Another approach could have been this:\n\n```ts\nif (pin.isExact) {\n  if (!pin.major) throw new Error(`Bad pin data!`)\n  doSomething(pin.major)\n}\n```\n\nSo, poor data modelling affects the quality of our code by our code either needing to deal with apparently possible states that are actually impossible OR by our code carefully ignoring those impossible states. Both solutions are terrible because they make code harder to read. There is more code, and the chance that wires about impossible and possible states will cross becomes a real possibility leading to potential runtime errors.\n\nADTs solve this. Let's refactor our Pin type into an ADT to see how!\n\n```ts\ntype Pin = ExactPin | RangePin\n\ninterface ExactPin {\n  tag: `ExactPin`\n  patch: number\n  minor: number\n  major: number\n  release?: string\n  build?: string\n}\n\ninterface RangePin {\n  tag: `RangePin`\n  values: Array\u003c{\n    operator: `~` | `\u003e=` | `...` // etc.\n    isExact: boolean\n    patch: number\n    minor: number\n    major: number\n    release?: string\n    build?: string\n  }\u003e\n}\n```\n\nNow we've encoded the possible states we cared about. Our code quality increases:\n\n```ts\nif (pin.tag === 'ExactPin') {\n  doSomething(pin.major) // No problem, `pin` has been narrowed from `Pin` to `ExactPin`!\n}\n```\n\nWhen a developer deals with values of `Pin` type they will have an immediately much better understanding of the possible states.\n\nIn fact every optional property in some data represents possibly different state representations and thus potentially a use case for an ADT. So for example we could go further with our above data modelling and define things like `ExactPreReleasePin` and `ExactPreReleaseBuildPin`:\n\n```ts\ninterface ExactPreReleasePin {\n  tag: `ExactPreReleasePin`\n  patch: number\n  minor: number\n  major: number\n  release: string\n}\n```\n\n```ts\ninterface ExactPreReleaseBuildPin {\n  tag: `ExactPreReleasePin`\n  patch: number\n  minor: number\n  major: number\n  release: string\n  build: string\n}\n```\n\nOf course like any technique there is a point where ADT modelling is probably overkill for your use-case. That said, that line might be further out than you think. For example while the above might seem excessive, it actually answers a question the previous data modelling left ambiguous which is the question of, is the following state possible?\n\n```ts\nconst pin = {\n  isExact: true,\n  patch: 1,\n  minor: 2,\n  major: 3,\n  build: `5`,\n}\n```\n\nThe answer is no! But without the ADT that _fact_ would have to managed by humans, rather than the machine.\n\nAt scale, having well modelled data can be a life saver. The up front verbosity pays dividends downstream for all the impossible branches removed from programs' possibility space. ADTs help you (or your consumers) focus on what _can actually happen_.\n\n\u003c/br\u003e\u003c/br\u003e\n\n# Features\n\nAll code blocks below assume these imports:\n\n```ts\nimport { Alge } from 'alge'\nimport { z } from 'zod'\n```\n\n## Records\n\n### Definition (`.record`)\n\nUse the Record Builder to define a record. At a minimum you specify the name and schema. Names should be in [pascal case](https://techterms.com/definition/pascalcase) to avoid name collisions with the Alge API (see below).\n\n```ts\nconst Circle = Alge.record('Circle', {\n  radius: z.number().positive(),\n})\n```\n\nIf you already have a Zod Object defined from somewhere else you can just pass it in:\n\n```ts\nconst Circle = Alge.record('Circle', CircleSchema)\n```\n\n### Construction (`.create`)\n\nOnce you've defined a record with the Record Builder you get back a Record Controller. Use it to create instances of your record:\n\n```ts\nconst circle = Circle.create({ radius: 10 })\n// { _tag: 'circle', radius: 10 }\n```\n\nThe `_tag` property is present to track the name of your record. you normally shouldn't have to interact directly with it.\n\n### Input Defaults\n\nLeverage Zod to get defaults for your properties ([zod docs](https://github.com/colinhacks/zod#default)):\n\n```ts\nconst Circle = Alge.record('Circle', {\n  radius: z.number().positive().default(0),\n})\n\nconst circle = Circle.create()\n// { _tag: 'circle', radius: 0 }\n```\n\n### Input Transformation\n\nYou can use zod to perform input transformations:\n\n```ts\nconst Url = Alge.record('Url', {\n  // ...\n  path: z\n    .string()\n    .optional()\n    .transform((path) =\u003e (path === undefined ? '/' : path.trim() === '' ? '/' : path.trim())),\n})\n```\n\n### Input Validation\n\nInput is validated via Zod. For example a negative number where only positives are accepted.\n\n```ts\nconst circle = circle.create({ radius: -10 })\n// throws\n```\n\n### Update\n\nYou can update records. Updating creates shallow copies of data. The validation, transformations, defaults etc. setup on the zod schema will re-run on the update function ensuring data integrity. Any errors there will be thrown.\n\n```ts\nconst circleUpdated = circle.update(circle, { radius: 5 })\n```\n\n### Metadata\n\nThe controller gives you access to metadata about your record:\n\n```ts\ncircle.name // 'Circle'\ncircle.schema // a Zod schema instance\n```\n\n### Chaining API\n\nThere is a chaining API available which is more verbose but also affords more features (see further down).\n\n```ts\nconst Circle = Alge.record('Circle')\n  .schema({\n    radius: z.number().positive(),\n  })\n  .done()\n```\n\nLike in the shorthand form, if you already have a Zod Object defined from somewhere else you can just pass it in:\n\n```ts\nconst Circle = Alge.record('Circle').schema(CircleSchema).done()\n```\n\n### Codecs\n\n#### Definition (`.codec`)\n\nYou can define a named codec which allows your record to be encoded to/decoded from another representation.\n\nThe encoder (`to`) transforms your record into a string.\n\nThe decoder (`from`) transforms a string into your record, or `null` if the string is invalid.\n\n```ts\nconst Circle = Alge.record('Circle')\n  .schema({\n    radius: z.number().positive().default(1),\n  })\n  .codec('graphic', {\n    //    ^[1]\n    to: (circle) =\u003e `(${circle.radius})`,\n    from (string) =\u003e {\n      const match = string.match(^/\\((\\d+)\\)/$)\n      return match ? { radius: radius[1]! } : null\n    //               ^[2]\n    }\n  })\n  .done()\n```\n\nNotes:\n\n1. We give our codec a _name_. This name is used for the derived API (see \"usage\" below).\n2. When returning the parsed data for our record we do _not_ need to deal with the `_tag` property.\n\n#### Usage (`.to.`, `.from`)\n\nCodecs are exposed under the `.from` and `.to` (decoders/encoders) properties:\n\n```ts\nconst circle = Circle.create()\n// { _tag: 'Circle', radius: 1 }\n\nCircle.to.graphic(circle)\n// (1)\n\nCircle.from.graphic(`(1)`)\n// { _tag: 'Circle', radius: 1 }\n\nCircle.from.graphic(`()`)\n// null\n```\n\n#### Built In JSON\n\nAll records have a JSON codec:\n\n```ts\nCircle.to.json(circle)\n// '{ \"_tag\": \"Circle\", \"radius\": 1 }'\n\nCircle.from.json('{ \"_tag\": \"Circle\", \"radius\": 1 }')\n// { _tag: 'Circle', radius: 1 }\n```\n\n#### OrThrow Decoders\n\nAll decoders, JSON or your custom ones, have a variant of decode that will throw an `Error` when decoding fails:\n\n```ts\nCircle.from.graphicOrThrow(`()`)\n// throws\n\nCircle.from.jsonOrThrow(`bad`)\n// throws\n```\n\n## Data (Algebraic Data Types)\n\nThe ADT Builder is an extension of the Record Builder and the ADT Controller it returns is an extension of the Record Controller.\n\n### Definition\n\n#### Referencing Records\n\nRecords can be passes into the Data Builder:\n\n```ts\nconst Circle = Alge.record('Circle', { radius: z.number() })\nconst Square = Alge.record('Square', { size: z.number() })\n\nconst Shape = Alge.data('Shape', { Circle, Square })\n```\n\n#### Inline Records\n\nRecords can also be defined inline:\n\n```ts\nconst Shape = Alge.data('Shape', {\n  Circle: { radius: z.number() },\n  Square: { size: z.number() },\n})\n```\n\n#### Referencing Zod Objects\n\nExisting Zod object schemas are also accepted:\n\n```ts\nconst Circle = z.object({ radius: z.number() })\nconst Square = z.object({ size: z.number() })\nconst Shape = Alge.data('Shape', { Circle, Square })\n```\n\n### Construction\n\nThe ADT Controller contains one Record Controller for every record defined under a property of that records name. Use it just like you did before:\n\n```ts\nconst circle = Shape.Circle.create({ radius: 1 })\n// { _tag: 'Circle', radius: 1 }\nconst square = Shape.Square.create({ size: 2 })\n// { _tag: 'Square', size: 2 }\n```\n\n### Chaining API\n\nAs with records before there is a chaining API for ADTs that is more verbose but has additional features.\n\n```ts\nconst Shape = Alge.data('shape').record(Circle).record(Square).done()\n```\n\nAs with the shorthand your existing Zod objects can be passed in:\n\n```ts\nconst CircleSchema = z.object({ radius: z.number() })\nconst SquareSchema = z.object({ size: z.number() })\nconst Shape = Alge.data('shape')\n  .record('Circle')\n  .schema(CircleSchema)\n  .record('Square')\n  .schema(SquareSchema)\n  .done()\n```\n\n### Identity (`.is`, `.is$`)\n\nUse the `.is` Record Controller method as a TypeScript type guard. It checks if the given value is that record or not:\n\n```ts\nconst onlyCircle = (shape: Shape): null | Shape.Circle =\u003e {\n  return Shape.Circle.is(shape) ? shape : null\n}\n```\n\nWhen you're working with unknown values there is the `.$is` method which takes `unknown` input. It is less type safe than `.is` so avoid `.is$` when you can:\n\n```ts\nconst onlyCircle = (someValue: unknown): null | Shape.Circle =\u003e {\n  return Shape.Circle.$is(someValue) ? someValue : null\n}\n```\n\n### Codecs\n\nWhen a codec of some name is defined for every record in an ADT then something special happens. The ADT gets access to a generalized version of the codec with these features:\n\n1. A generalized decoder that will take a string and return a record instance of the first record decoder to return non-null. The static type is a union of all the records in the ADT (plus `null`).\n2. A generalized encoder that will dispatch automatically to the correct Record encoder based on the passed in record's `_tag` value.\n\n#### Definition (`.codec`)\n\nHere is an example of defining a custom codec for each record in an ADT.\n\n```ts\nconst circlePattern = /^\\(( *)\\)$/\nconst squarePattern = /^\\[( *)\\]$/\n\nconst shape = Alge.data('Shape')\n  .record(`Circle`)\n  .schema({\n    radius: z.number(),\n  })\n  .codec('graphic', {\n    to: (circle) =\u003e `(${' '.repeat(circle.radius)})`,\n    from: (string) =\u003e {\n      const match = string.exec(circleString)\n      return match ? { radius: match[1]!.length } : null\n    },\n  })\n  .record(`square`)\n  .schema({\n    size: z.number(),\n  })\n  .codec('graphic', {\n    to: (square) =\u003e `[${' '.repeat(square.size)}]`,\n    from: (string) =\u003e {\n      const match = squarePattern.exec(string)\n      return match ? { size: match[1]!.length } : null\n    },\n  })\n  .done()\n```\n\n#### Usage (`to`, `from`)\n\n```ts\nconst circle = Shape.Circle.create({ radius: 3 })\n// { _tag: 'circle', radius: 3 }\nconst circleString = Shape.Circle.to.graphic(circle)\n// '(   )'\nconst circle2 = Shape.Circle.from.graphic(circleString)\n// { _tag: 'circle', radius: 3 }\nconst circle3 = Shape.Circle.from.graphic('(]')\n// null\nconst shape1 = shape.from.graphic('()')\n// type: circle | square | null\n// value: { _tag: 'circle', radius: 0 }\nconst shape2 = Shape.from.graphic('[]')\n// type: circle | square | null\n// value: { _tag: 'square', size: 0 }\nconst shape3 = Shape.from.graphic('!')\n// type: circle | square | null\n// value: null\nconst shape4 = Shape.from.graphicOrThrow('!')\n// type: circle | square\n// value: throws\n```\n\nAs mentioned all records have a JSON codec, thus all ADTs have a generalized one.\n\n```ts\nconst circleJson = Shape.to.json(circle)\n// '{ \"_tag\": \"circle\", \"radius\": 50 }'\nconst circle2 = shape.from.json(circleJson)\n// { \"_tag\": \"circle\", \"radius\": 50 }\n```\n\n## Static Types\n\nOften you will write code (e.g. your own functions) that need to be typed with your adt. alge has \"type functions\" for this which leverages typescript inference.\n\nFor adts there is `alge.Infer`. it return an object with a property _per_ record of the adt _as well as_ a special property `*` which is _a union of all records_.\n\n```ts\ntype Shape = Alge.Infer\u003ctypeof shape\u003e\n/*\n{\n  Circle: { _tag: 'Circle', radius: number }\n  Square: { _tag: 'Square', size: number }\n  '*':    | { _tag: 'Circle', radius: number }\n          | { _tag: 'Square', size: number }\n}\n*/\n\nconst doSomething = (shape: Shape['*']): null | Shape['circle'] =\u003e {\n  // todo\n}\n```\n\nFor lone records there is `alge.InferRecord`.\n\n```ts\ntype Circle = Alge.InferRecord\u003ctypeof Circle\u003e\n\nconst doSomething = (circle: Circle) =\u003e {\n  // todo\n}\n```\n\n### Namespaces\n\nWhen working with inferred adt types, if you prefer to work with namespaces rather than objects to reference types you can use the following pattern:\n\n```ts\ntype ShapeInferred = Alge.Infer\u003ctypeof Shape\u003e\n\ntype Shape = ShapeInferred['*']\n\nnamespace Shape {\n  export type Circle = ShapeInferred['Circle']\n  export type Square = ShapeInferred['Square']\n}\n\nconst doSomething = (shape: Shape): null | Shape.Circle =\u003e {\n  // todo\n}\n```\n\n## String Literal Union Pattern Matching\n\nUse `.match` to dispatch code execution based on data patterns. Among other things you can match on unions of string literals. The flow is:\n\n- Pass your value to `Alge.match` to begin the pattern matching.\n- Chain tag matchers\n- Finish with `.done()` to statically verify union exhaustiveness or `.else(...)` if you want to specify a fallback value.\n\n### Tag Matchers\n\nTag Matchers simply branch based on the string literal. You call `.done()` to perform the exhaustiveness check. If you can't call this (because of static type error) then your pattern matching is not exhaustive. This catches bugs!\n\n```ts\nconst randomThing = pickRandom(['lego', 'basketball', 'videoGame'])\nconst sentence = Alge.match(randomThing)\n  .lego(() =\u003e `Got Lego!`)\n  .basketball(() =\u003e `Got Basketball`)\n  .videoGame(() =\u003e `Got video game!`)\n  .done()\n```\n\n### Done Versus Else\n\nWhen you don't want to be exhaustive, use `else` instead of `done`. The value you specify in `else` will be used if no matcher matches.\n\n```ts\nconst randomThing = pickRandom(['lego', 'rockClimbing', 'hiking'])\n\nconst sentence = Alge.match(randomThing)\n  .lego(() =\u003e `Got a toy!`)\n  .else((thing) =\u003e `Got an activity! (${thing})`)\n\nconst maybeLego = Alge.match(randomThing)\n  .lego(() =\u003e 'Got Lego!')\n  .else(null)\n```\n\n## ADT Pattern Matching\n\nUse `.match` to dispatch code execution based on data patterns. Among other things You can match on your ADT's variants either by their tag or a data pattern. The flow is:\n\n- Pass your value to `Alge.match` to begin the pattern matching.\n- Chain tag or data (or both) matchers\n- Finish with `.done()` to statically verify variant exhaustiveness or `.else(...)` if you want to specify a fallback value.\n\nYou can see some examples in action [here](./examples/Match.ts).\n\n### Tag Matchers\n\nTag Matchers simply branch based on the variant's tag property. The tag property can be any of the following. The first one found in the following order is used. so for example if both `_kind` and `type` are present then `_kind` is considered the tag property.\n\n- `__typename` (this is helpful if you're working with GraphQL unions)\n- `_tag`\n- `_type`\n- `_kind`\n- `type`\n- `kind`\n\nYou call `.done()` to perform the exhaustiveness check. If you can't call this (because of static type error) then your pattern matching is not exhaustive. This catches bugs!\n\n```ts\nconst result = Alge.match(shape)\n  .Circle((circle) =\u003e `Got a circle of radius ${circle.radius}!`)\n  .Square((square) =\u003e `Got a square of size ${square.size}!`)\n  .done()\n```\n\n### Value Matchers\n\nValue Matchers allow you to specify that the branch only matches when the actually data of the variant also matches your criteria.\n\nSince these kinds of matchers are dynamic you cannot use `.done` with them but instead must use `.else` to specify a fallback value in case they do not match.\n\n```ts\nconst result = Alge.match(shape)\n  .Circle({ radius: 13 }, () =\u003e `Got an unlucky circle!`)\n  .Square({ size: 13 }, () =\u003e `Got an unlucky square!`)\n  .else({ ok: true })\n```\n\n### Mixing Matchers\n\nYou can mix matchers. Order matters. More specific matchers must come before more general matchers. Alge automates these checks for you:\n\n- Cannot specify a value matcher _after_ a tag matcher (static \u0026 runtime enforcement)\n- Future Feature (#todo-issue)[https://github.com/jasonkuhrt/alge/issues/todo]: Cannot specify a more specific data matcher after a less specific one\n\n```ts\nconst result = Alge.match(shape)\n  .Circle({ radius: 13 }, () =\u003e `Got an unlucky circle!`)\n  .Circle((circle) =\u003e `Got a circle of radius ${circle.radius}!`)\n  .Square({ size: 13 }, () =\u003e `Got an unlucky square!`)\n  .Square((square) =\u003e `Got a square of size ${square.size}!`)\n  .done()\n```\n\n### Done Versus Else\n\nWhen you don't want to be exhaustive, use `else` instead of `done`. The value you specify in `else` will be used if no matcher matches.\n\n```ts\nconst result = Alge.match(shape)\n  .Circle((circle) =\u003e `Got a circle of radius ${circle.radius}!`)\n  .else(null)\n```\n\nIf you don't want your else to be an eager value, make it lazy with a function. Also this gives you access to the data (with its type statically narrowed):\n\n```ts\nconst result = Alge.match(shape)\n  .Circle((circle) =\u003e `Got a circle of radius ${circle.radius}!`)\n  .else((shape) =\u003e (Math.random() \u003e 0.5 ? [1, shape] : [2, shape]))\n```\n\n\u003c/br\u003e\u003c/br\u003e\n\n![alt](https://repobeats.axiom.co/api/embed/3c932f1cb76da4ad21328bfdd0ad1c6fbbe76a0b.svg 'repobeats analytics image')\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonkuhrt%2Falge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasonkuhrt%2Falge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonkuhrt%2Falge/lists"}