Skip to content

Add type annotation and compound unit docs to dim-si README#5

Closed
dyreby wants to merge 1 commit intomainfrom
docs/type-annotations-compound-units
Closed

Add type annotation and compound unit docs to dim-si README#5
dyreby wants to merge 1 commit intomainfrom
docs/type-annotations-compound-units

Conversation

@dyreby
Copy link

@dyreby dyreby commented Feb 12, 2026

Add two sections to the dim-si README:

Type Annotations

Shows how to annotate function parameters and return types using Quantity<D> wrapper with dimension types like Length, Time, Velocity.

Compound Units

Shows how to create units like km/h by combining scale factors from existing units.


Closes #7

Document how to annotate function parameters and return types using
Quantity<D> wrapper with dimension types.

Show pattern for creating compound units like km/h by combining scale
factors from existing units.

Addresses #4
@dyreby dyreby added documentation Improvements or additions to documentation pkg:dim-si dim-si package labels Feb 12, 2026
@dyreby dyreby requested a review from gdtroszak February 12, 2026 20:46
@dyreby
Copy link
Author

dyreby commented Feb 12, 2026

Note: This was drafted by my agent. If anything here is annoying or seems off, I'd appreciate an issue at https://github.com/dyreby/agent-stuff so I can improve it.

@gdtroszak
Copy link
Contributor

The Type Annotations example imports Quantity from @isentropic/dim-quantity, but users of dim-si shouldn't need to reach into that package directly. dim-si should re-export the types they need.

Specifically, Linear and Affine (from dim-unit) are the right types for function annotations — they express whether a parameter is a regular quantity or an affine one (like absolute temperature). Quantity itself isn't needed since Linear and Affine cover both cases.

Proposed changes:

  1. Re-export Linear and Affine from @isentropic/dim-si (root module)
  2. Update the Type Annotations example to use Linear:
import type { Linear } from "@isentropic/dim-si";
import type { Length } from "@isentropic/dim-si/length";
import type { Time } from "@isentropic/dim-si/time";
import type { Velocity } from "@isentropic/dim-si/velocity";
import { divide } from "@isentropic/dim-si/ops";

function speed(
  distance: Linear<Length>,
  duration: Linear<Time>,
): Linear<Velocity> {
  return divide(distance, duration);
}
  1. Add an Affine example to show the distinction:
import type { Affine } from "@isentropic/dim-si";
import type { Temperature } from "@isentropic/dim-si/temperature";
import { kelvin } from "@isentropic/dim-si/temperature";
import { q } from "@isentropic/dim-si/ops";

function toKelvin(temp: Affine<Temperature>): number {
  return q(temp).in(kelvin);
}
  1. Update the prose to explain Linear vs Affine instead of referencing Quantity.

return divide(distance, duration);
}
```

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels like it could live in the Quick Start rather than its own section — it's a natural next step after using built-in units.

@gdtroszak
Copy link
Contributor

Closing this for now. I need to think more about what types to expose before providing guidance on type annotations and compound units. Will revisit in #7.

@gdtroszak gdtroszak closed this Feb 13, 2026
@gdtroszak gdtroszak deleted the docs/type-annotations-compound-units branch February 13, 2026 11:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation pkg:dim-si dim-si package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make dim-si types easy to use for end users

2 participants