[btravers]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

@btravstack/entity@0.8.0

Minor Changes

• 83af66b: Entity.aggregate(tag)(fields)(options) declares an aggregate root whose state
  changes only through events. The options declare the events (a zod
  discriminated union on type), an opens handler per creation event and an
  evolve handler per other event; omitting one is a compile error.

  • An aggregate has no update() and no factories. A command checks its
    business rules and calls this.emit(...events), which parses the events,
    folds them, verifies the result with one make, and returns a sealed
    Entity.Decision: the events and the verified state. Only emit and
    start can build one, and events that break an invariant are a defect.
  • SomeAggregate.start(event) creates from a creation event.
    SomeAggregate.replay(events) parses and folds a stored stream; make
    still rehydrates a snapshot or a state row. Neither emits events.
  • The same aggregate persists as state plus an outbox or as an event stream
    without changing its declaration.

  Entity keeps its API. Four new top-level declaration-emit names:
  AggregateStatic, AggregateInstance, Decision, DecisionKey, plus
  Entity.Decision, Entity.Event and Entity.Aggregate in the namespace.

• 1729958: Breaking: structural equals is removed, and entities compare by declared
  identity instead.

  • Entity.field(schema, { identity: true }) marks a field as part of the
    entity's business identity. Several flagged fields form a composite
    identity. It implies immutable, and the value must be a required primitive.
  • entity.sameIdentityAs(other) is true when other is in the same identity
    scope and every identity field is equal by Object.is. The scope is the
    class that declares the identity, or the abstract root when it is declared
    there, so a root's variants (a draft and the document it became) share it.
    On an entity with no identity field, calling it is a compile error.
  • equals is gone, and with it the package's only Node import
    (node:util's isDeepStrictEqual), so the package now bundles for the
    browser. To compare two whole states, compare their toJSON() with your own
    deep-equality function.
  • sameIdentityAs replaces equals as a reserved field name.

  To migrate, flag your id fields identity: true and replace a.equals(b) with
  a.sameIdentityAs(b) where you meant "the same entity", or with a deep
  comparison of toJSON() where you meant "the same state".

• aab342b: Add SomeEntity.inspect(state), a read-side door for stored rows written before a rule existed. It validates the field schemas strictly and re-derives computed like make, then reports every broken invariant instead of refusing the row: Result<Inspection<Output>, InvalidEntity>, where Inspection is { data, violations }.

  data is plain frozen data, never an entity instance, so a row that breaks today's rules cannot reach a command by accident. The way back is a migration, then make, which stays strict. violations are the issues make would have failed with, so Entity.codeOf reads them. A field failure is still InvalidEntity, a throwing predicate is still a defect, and a nested entity field is inspected strictly.

  Entity.union gains inspect too, dispatching on the discriminant. Inspection joins the top-level declaration-emit names, with Entity.Inspection for annotations. The new how-to, "Add a stricter rule without an outage", covers the rollout.

• 20dcfc2: Breaking: Entity.invariant now takes one object with a required stable
  code:

  Entity.invariant({
    code: "NAME_TOO_LONG",
    ensure: (d) => d.name.length <= 80,
    message: "name must be at most 80 characters",
  });

  The code is the rule's identity, which a caller keys behaviour off (an error
  code in a response, a field to highlight, a localised string), while the
  message may vary with the data. A failing rule's issue is now
  { message, params: { code } }; the code survives nested entities, arrays and
  unions with the path prefixed, and the new Entity.codeOf(issue) reads it back.

  To migrate, wrap each Entity.invariant(ensure, message) as
  Entity.invariant({ code, ensure, message }). A missing code is a compile
  error.

• 4d79b0e: Breaking: input, output, createInput and updateInput are plain all
  the way down, so an entity with a nested-entity field converts to JSON Schema
  (No wire projection: nested entities break z.toJSONSchema, and undefined/null is bridged by hand at every boundary #72).

  • A field holding another entity, an array of entities, an optional or
    nullable one, or an Entity.union(...) now embeds the nested entity's own
    plain schema in each member: its input in input, createInput and
    updateInput, its output (computed fields included) in output. A union
    becomes a discriminated union of its members' plain schemas. Every member
    converts with z.toJSONSchema in both directions, at any depth; before, all
    of them threw.
  • make, update and the factories are unchanged: they parse through an
    internal schema that keeps the classes, so a nested field still holds a real
    instance.
  • updateInput is now derived from input rather than output. Its keys are
    the same; only a nested entity's schema differs.
  • An Entity.union(...) value's input and output are typed from its
    members' schemas instead of z.ZodType<unknown>.

  To migrate: parsing with a member now yields plain data at every depth, so
  Order.output.parse(x).lines[0] is an object, not an OrderLine. Code that
  relied on a member to construct nested instances should call make instead,
  which is the entry point for building entities. Types follow suit:
  z.output<typeof Order.output> describes plain nested data, while
  Entity.Output<typeof Order> and the instance types still carry the nested
  entities.

• f3b42e3: Entity.field(schema, { unbranded: true }) exempts one field from the rule
  that every field be branded, an entity or a narrow literal. It is meant for a
  descriptive leaf (a label, a display name) with no second value it could be
  confused with, whose brand would otherwise leak into every consumer of the
  derived schemas. The field is still validated and still honours immutable;
  only the branding rule is relaxed, and only for that field. Existing
  declarations are unchanged, and their emitted declarations do not grow.

Patch Changes

• 8d928cd: A downstream library compiling with declaration: true can now export a value
  whose inferred type runs a branded object through the package's deep-readonly
  data type. That includes SomeEntity.factory(...) for an entity with a
  nested-entity field. Declaration emit used to fail with TS4023 ($brand
  cannot be named); the brand now prints as z.$brand<…>.

• 02c29e3: Document the self-referencing deriver idiom (computed derivers cannot reference the entity's own statics (TS2506) #60): a computed deriver or an
  Entity.invariant predicate may call the entity's own statics, given an
  explicit return annotation — (d): boolean => Doc.isActive(d.tags). The
  unannotated form is TS2506, which is TypeScript resolving the deriver's
  inferred return type inside the class's own base expression, not a rule of
  the library. The annotation is still checked against both the body and the
  schema. computed.test-d.ts pins the idiom, the wrong-annotation errors, and
  the this-parameter dead end (TS2502).

  Documentation only; no runtime or API change.

• 08aca24: A synchronous generator that throws no longer escapes factory(...)'s returned
  function: the factory now returns a Defect carrying the original cause, the
  same channel a rejecting generator already takes under factoryAsync.

[Copilot]

Pull request overview

Release automation PR for @btravstack/entity that prepares the repository metadata for publishing version 0.7.1 to npm (per Changesets), reflecting a documentation-only patch associated with issue #60.

Changes:

• Bump @btravstack/entity version to 0.7.1.
• Add 0.7.1 release notes to the package changelog.
• Remove the consumed changeset file now that it has been released.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
packages/entity/package.json	Updates the package version to 0.7.1 for publication.
packages/entity/CHANGELOG.md	Adds the 0.7.1 patch entry describing the documentation-only change.
.changeset/computed-self-reference-annotation.md	Removes the changeset after it has been applied to the release.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: btravstack/entity/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 09ebdda5-abcb-41b8-8364-375126ab1abe

📥 Commits

Reviewing files that changed from the base of the PR and between a84f436 and 8e615d5.

📒 Files selected for processing (3)

• .changeset/branded-object-declaration-emit.md
• .changeset/factory-throwing-generator.md
• packages/entity/CHANGELOG.md

💤 Files with no reviewable changes (2)

• .changeset/factory-throwing-generator.md
• .changeset/branded-object-declaration-emit.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/entity/CHANGELOG.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The package version changed from 0.7.0 to 0.8.0. The changelog records equality behavior and its Node.js requirement, branded declaration emit, self-referencing annotations, and synchronous generator failure handling. Two changesets were removed.

Changes

Entity package release

Layer / File(s)	Summary
Version and changelog updates packages/entity/package.json, packages/entity/CHANGELOG.md, .changeset/*	The package version is now 0.8.0. The changelog records equality behavior, its Node.js requirement, branded declaration emit, self-referencing annotations, and synchronous generator failure handling. Two changesets for documented changes were removed.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 8e615

This release-metadata change bumps the package to 0.8.0 and records the changelog entries. No merge-blocking issues were found.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the release preparation for @btravstack/entity``@0.8.0.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}