jasonkuhrt / alge Goto Github PK

Perceived Problem

Input is not validated so at construction time an invalid email could be given etc.

Ideas / Proposed Solution(s)

Use zod schema parse function
Consider a way to opt out for performance sensitive reasons

Screenshot

Getting this TS error in Molt Command:

src/ParameterSpec/validate.ts:6:14 - error TS2742: The inferred type of 'Result' cannot be named without a reference to '../../node_modules/alge/dist/esm/core/types.js'. This is likely not portable. A type annotation is necessary.

6 export const Result = Alge.data(`Result`, {
               ~~~~~~

src/ParameterSpec/validate.ts:6:14 - error TS2742: The inferred type of 'Result' cannot be named without a reference to '../../node_modules/alge/dist/esm/data/types/Controller.js'. This is likely not portable. A type annotation is necessary.

6 export const Result = Alge.data(`Result`, {
               ~~~~~~

src/ParameterSpec/validate.ts:6:14 - error TS2742: The inferred type of 'Result' cannot be named without a reference to '../../node_modules/alge/dist/esm/record/types/StoredRecord.js'. This is likely not portable. A type annotation is necessary.

6 export const Result = Alge.data(`Result`, {
               ~~~~~~


Found 3 errors in the same file, starting at: src/ParameterSpec/validate.ts:6

Description

Try fixing this by exporting types from Alge...

See if having another exported entrypoint of alge/types solves this for the consumer.

Repro Steps/Link

Perceived Problem

Tag is implied from the method:

Ideas / Proposed Solution(s)

Update TS types to hide it.

Perceived Problem

Currently you can do this:

const Square = Alge.data('shape', {
  Square: { ...  },
  Circle: { ... },
  Rectangle: { ... },
})

But not this:

const Rectangle = z.object({ ... })
const Square = z.object({ ... })
const Circle = z.object({ ... })

const Square = Alge.data('shape', {
  Square,
  Circle,
  Rectangle,
})

In other words we accept: Record<string, z.ZodType<unknown>> but not z.SomeZodObject. Not supporting this overload feels like a lost incremental opportunity.

Ideas / Proposed Solution(s)

Support it.

Perceived Problem

There is a concept of extensions, which is the ability in the builder to add custom api surface area to the controller.

We actually use this feature in our examples: https://github.com/jasonkuhrt/alge/blob/main/examples/Moniker.ts#L45-L62

This is not documented.

Ideas / Proposed Solution(s)

Document it in our features. This is probably a new category, either before or after codecs, but lower anyways, since it is perhaps more advanced.

Hey 👋
Thanks for creating this awesome library.

Is it possible to change the name of the tag field for JSON codecs?
I want to use a different name for the field and not "_tag". It's not a hard blocker but just wanted to check if there is a configuration option that supports this.

Screenshot

Description

size2 should not be allowed because it is not a known property. (Notice size is not required because it has a default).

Perceived Problem

There are some utility types that sometimes need referencing:

• Record constructor input
• ...

Ideas / Proposed Solution(s)

• Make them available from infer

Perceived Problem

Alge currently can only be consumed by ESM packages/projects. This leaves out too many people in the community I feel.

Ideas / Proposed Solution(s)

I'm actually not sure what the mechanism to support both ESM and CJS is anymore. I am already fairly knowledgeable but hopefully there's just something simple I don't know yet. Anyways, more research to do.

Screenshot

Description

_ should not be passed through.

Perceived Problem

• Zod has the concept of defaults https://github.com/colinhacks/zod#default

Ideas / Proposed Solution(s)

• When used we should honour that and not require the constructor to provide the input
• Note this overlaps with the native defaults feature
• Run zod defaults AFTER the native defaults system

Perceived Problem

The _tag property is supposed to be an implementation detail.
If wishing to pattern match on every case of an ADT it becomes necessary to use it IF wishing to use the switch-case syntax:

switch (someAdtValue._tag) {
	case: 'foo': ...
	case: 'bar': ...
	...
}

Ideas / Proposed Solution(s)

Need to think about API ideas. Prior art:

• https://dev.to/gvergnaud/bringing-pattern-matching-to-typescript-introducing-ts-pattern-v3-0-o1k
• https://github.com/gvergnaud/ts-pattern

What

Why

How

Perceived Problem

We've got some basic docs in the readme but no thorough inline documentation.

Ideas / Proposed Solution(s)

Make JSDoc first class documentation and probably have a policy of it being the source of truth.

What

Terminology:

Code:

Alge.data(...).variant(...).schema(...)
Alge.datum(...).schema(...)

What we talk about:

• "controller"
• "builder"

Why

This is 6 terms :/. Can we make this simpler?

How

Words instead of data: adt, union, create, build, make, ...

I'd like to merge variant and datum because they are basically the same just in a different context, variant/datum: model, record, struct, ...

As for schema, it is the one that bothers me least but there are alternatives here too: shape, ...

Examples:

Alge.union(...).record(...).schema(...)
Alge.record(...).schema(...)

Alge.union(...).record(...).shape(...)
Alge.record(...).shape(...)

Alge.adt(...).model(...).schema(...)
Alge.model(...).schema(...)

Right now I think union + record + schema is a sweet spot:

• union nudges toward formal and TS terminology
• record nudges toward Haskell terminology (for product types), what Prisma generally refers for database rows (Postgres etc.)/documents (mongo etc.), and TS term for objects. Re TS I'm of two minds because actually in TS records are indexed types which are are a different beast and arguably make the term overlap more confusing, on the there hand its still objects/data and in that regard make the overlap helpful.
• schema is a common term for what we are doing in Alge as well. It does get blurry in that sometimes schemas mean validation as well, but other times just types, which in turn is variable according to what the type system can represent. shape is cute and feels maybe a little less technical, but in this case I think it might add more confusion than not.

It can dispatch to member update functions based on tag. Of course the algorithm is the same for each so it doesn't even need to do that. It simply needs to adjust the types of the changes parameter.

Perceived Problem

From #83 (comment)

Realized an advanced type refinement feature we could have. But save for a future issue.

const Shape = Alge.data('Shape')
  .record('Circle', { color: z.string().optional(), radius: z.number() })
  .record('Square', { color: z.string().optional(), size: z.number() })

/* ... */

const result = Alge.match(shape).Circle({ color: 'red' }, (data) => data)
//                                                         1

1. The data that comes through should have color: 'red' instead of color?: string since the pattern match guarantees that.

Ideas / Proposed Solution(s)

Implement this.

Perceived Problem

@Weakky pointed out that for simple cases the current API is verbose. I agree!

Ideas / Proposed Solution(s)

I sketched out some alternatives here: https://gist.github.com/jasonkuhrt/7ad238bcc13e853ff7456f624f794879

I think this could work:

//--------------------------------------------------------------------------------------
// Centralized

const Shape = Alge.union(`Shape`, {
  Rectangle: {
    width: Length,
    height: Length,
  },
  Circle: {
    radius: Length,
  },
  Square: {
    size: Length,
  },
})

//--------------------------------------------------------------------------------------
// Separated

const Rectangle = Alge.record(`Rectangle`, {
  width: Length,
  height: Length,
})

const Circle = Alge.record(`Circle`, {
  radius: Length,
})

const Square = Alge.record(`Square`, {
  size: Length,
})

const Shape = Alge.union(`Shape`, {
  Rectangle,
  Circle,
  Square,
})

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update devdependencies (non-major) (@swc/core, @swc/helpers, @types/node, @types/semver, @typescript-eslint/eslint-plugin, @typescript-eslint/parser, eslint, eslint-plugin-codegen, prettier, semver, ts-node, tsd)
• chore(deps): update pnpm to v8.15.3
• chore(deps): update devdependencies (major) (major) (@typescript-eslint/eslint-plugin, @typescript-eslint/parser, eslint-plugin-simple-import-sort, vitest)
• chore: update actions/cache action to v4
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

Perceived Problem

It is possible for the constructor input to be transformed. We actually use this feature in our of our examples: https://github.com/jasonkuhrt/alge/blob/main/examples/Moniker.ts#L24.

This is not documented.

Ideas / Proposed Solution(s)

Add a new section, probably under schema, maybe called input transformations. Perhaps rename Property Defaults to Input defaults. Being explicit between input/output is generally good I think.