[indietyp]

🌟 Purpose

Create a first vertical slice of the TypeScript SDK, for constructing HashQL queries. The foundation is laid, but not all types are there, which lets us prototype (fast) new approaches. The first approach is Do notation, which was found to be awkward for JS devs. Other experiments will follow.

🔍 Changes

• The builder keeps module, value and type environments separate across declarations, imports and nested blocks. Expression handles carry semantic types through calls, projections and query filters.
• Input requirements compose with expressions. Program.Inputs exposes required and defaulted inputs, including dependencies from both conditional branches and emitted bindings.
• Expected construction failures compose as Effect Result values. Program.compile serializes the constructed tree to J-Expr without rerunning authoring callbacks.
• Module declarations supply the semantic annotations used by the TypeScript authoring API. Name resolution and query type checking belong to the HashQL compiler.

Start with libs/@local/hashql/sdk/typescript/docs/authoring.md. The checked API examples and examples/filters.ts show how the typed constructions compare with existing queries.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Oct 19, 2026 6:00pm UTC
petrinaut	Ready	Preview	Oct 19, 2026 6:00pm UTC
petrinaut-docs	Ready	Preview	Oct 19, 2026 6:00pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Oct 19, 2026 6:00pm UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (bm/be-992-add-the-localhashql-typescript-package@c757133). Learn more about missing BASE report.

Additional details and impacted files

@@                                 Coverage Diff                                 @@
##             bm/be-992-add-the-localhashql-typescript-package   #10013   +/-   ##
===================================================================================
  Coverage                                                    ?   68.03%           
===================================================================================
  Files                                                       ?     2000           
  Lines                                                       ?   205702           
  Branches                                                    ?     8774           
===================================================================================
  Hits                                                        ?   139950           
  Misses                                                      ?    64087           
  Partials                                                    ?     1665           

Flag	Coverage Δ
apps.hash-ai-worker-ts	6.85% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codspeed]

Merging this PR will not alter performance

⚠️ 6 benchmarks measured no execution time

Nothing ran under measurement, usually because the compiler removed the code under test. These results are not comparable, so they count as unchanged.

Preventing compiler optimizations

• as_constant
• constant_equal
• constant_not_equal
• access
• runtime_equal
• runtime_not_equal

⚠️ 1 benchmark spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• bit_matrix/dense/union_rows[1000]

✅ 98 untouched benchmarks

---

_{Comparing bm/be-946-create-a-vertical-slice-of-the-typescript-sdk (45b6f98) with main (d3c0347)¹}

Footnotes

1. No successful run was found on bm/be-992-add-the-localhashql-typescript-package (c757133) during the generation of this report, so main (d3c0347) was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[github-actions]

Benchmark results

hash-graph-benches – Integrations

policy_resolution_large

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 2002	$$28.7 \mathrm{ms} \pm 243 \mathrm{μs}\left({\color{gray}-2.671 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.75 \mathrm{ms} \pm 34.7 \mathrm{μs}\left({\color{gray}4.76 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 1002	$$14.7 \mathrm{ms} \pm 173 \mathrm{μs}\left({\color{red}7.11 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 3314	$$46.6 \mathrm{ms} \pm 486 \mathrm{μs}\left({\color{gray}-0.828 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$15.4 \mathrm{ms} \pm 139 \mathrm{μs}\left({\color{gray}-4.048 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 1527	$$26.4 \mathrm{ms} \pm 362 \mathrm{μs}\left({\color{gray}-1.132 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 2078	$$29.8 \mathrm{ms} \pm 342 \mathrm{μs}\left({\color{gray}-4.166 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.91 \mathrm{ms} \pm 32.6 \mathrm{μs}\left({\color{gray}-2.655 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 1033	$$15.0 \mathrm{ms} \pm 170 \mathrm{μs}\left({\color{gray}-2.224 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_medium

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 102	$$3.98 \mathrm{ms} \pm 53.2 \mathrm{μs}\left({\color{gray}-0.872 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.11 \mathrm{ms} \pm 27.4 \mathrm{μs}\left({\color{gray}0.643 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 52	$$3.51 \mathrm{ms} \pm 30.9 \mathrm{μs}\left({\color{gray}-0.878 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 269	$$5.37 \mathrm{ms} \pm 45.0 \mathrm{μs}\left({\color{gray}-2.793 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$3.66 \mathrm{ms} \pm 41.7 \mathrm{μs}\left({\color{gray}-2.748 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 108	$$4.32 \mathrm{ms} \pm 40.7 \mathrm{μs}\left({\color{gray}-1.037 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 133	$$4.80 \mathrm{ms} \pm 52.1 \mathrm{μs}\left({\color{gray}-2.841 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.56 \mathrm{ms} \pm 30.3 \mathrm{μs}\left({\color{gray}-3.522 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 63	$$4.41 \mathrm{ms} \pm 39.5 \mathrm{μs}\left({\color{gray}-2.637 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_none

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 2	$$2.83 \mathrm{ms} \pm 25.5 \mathrm{μs}\left({\color{lightgreen}-6.826 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.87 \mathrm{ms} \pm 26.4 \mathrm{μs}\left({\color{gray}-0.972 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 2	$$2.93 \mathrm{ms} \pm 25.4 \mathrm{μs}\left({\color{gray}-1.190 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 8	$$3.22 \mathrm{ms} \pm 29.5 \mathrm{μs}\left({\color{gray}-0.965 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$2.95 \mathrm{ms} \pm 25.3 \mathrm{μs}\left({\color{gray}-2.131 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 3	$$3.34 \mathrm{ms} \pm 29.4 \mathrm{μs}\left({\color{gray}0.844 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_small

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 52	$$3.19 \mathrm{ms} \pm 29.3 \mathrm{μs}\left({\color{gray}-3.607 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.03 \mathrm{ms} \pm 28.0 \mathrm{μs}\left({\color{gray}3.41 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 26	$$3.13 \mathrm{ms} \pm 24.1 \mathrm{μs}\left({\color{gray}-0.583 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 94	$$3.77 \mathrm{ms} \pm 36.8 \mathrm{μs}\left({\color{gray}2.63 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$3.30 \mathrm{ms} \pm 32.0 \mathrm{μs}\left({\color{gray}3.20 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 27	$$3.43 \mathrm{ms} \pm 34.6 \mathrm{μs}\left({\color{gray}-1.333 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 66	$$3.61 \mathrm{ms} \pm 40.6 \mathrm{μs}\left({\color{gray}0.043 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.18 \mathrm{ms} \pm 26.1 \mathrm{μs}\left({\color{gray}-0.451 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 29	$$3.54 \mathrm{ms} \pm 36.3 \mathrm{μs}\left({\color{gray}1.68 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_complete

Function	Value	Mean	Flame graphs
entity_by_id;one_depth	1 entities	$$33.1 \mathrm{ms} \pm 255 \mathrm{μs}\left({\color{gray}-4.808 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	10 entities	$$73.1 \mathrm{ms} \pm 517 \mathrm{μs}\left({\color{lightgreen}-5.995 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	25 entities	$$38.6 \mathrm{ms} \pm 322 \mathrm{μs}\left({\color{gray}-1.929 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	5 entities	$$41.8 \mathrm{ms} \pm 383 \mathrm{μs}\left({\color{gray}-0.743 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	50 entities	$$45.5 \mathrm{ms} \pm 347 \mathrm{μs}\left({\color{gray}-1.329 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	1 entities	$$35.8 \mathrm{ms} \pm 274 \mathrm{μs}\left({\color{lightgreen}-5.005 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	10 entities	$$438 \mathrm{ms} \pm 1.80 \mathrm{ms}\left({\color{gray}0.342 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	25 entities	$$99.3 \mathrm{ms} \pm 920 \mathrm{μs}\left({\color{red}6.18 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	5 entities	$$84.8 \mathrm{ms} \pm 634 \mathrm{μs}\left({\color{gray}3.02 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	50 entities	$$299 \mathrm{ms} \pm 1.21 \mathrm{ms}\left({\color{gray}-3.781 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	1 entities	$$11.6 \mathrm{ms} \pm 74.1 \mathrm{μs}\left({\color{red}10.8 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	10 entities	$$11.7 \mathrm{ms} \pm 96.7 \mathrm{μs}\left({\color{red}9.69 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	25 entities	$$11.4 \mathrm{ms} \pm 86.3 \mathrm{μs}\left({\color{red}5.42 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	5 entities	$$11.7 \mathrm{ms} \pm 91.6 \mathrm{μs}\left({\color{red}11.2 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	50 entities	$$12.0 \mathrm{ms} \pm 150 \mathrm{μs}\left({\color{red}12.1 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_linkless

Function	Value	Mean	Flame graphs
entity_by_id	1 entities	$$11.5 \mathrm{ms} \pm 101 \mathrm{μs}\left({\color{red}8.14 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$11.2 \mathrm{ms} \pm 104 \mathrm{μs}\left({\color{red}6.07 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$11.1 \mathrm{ms} \pm 87.0 \mathrm{μs}\left({\color{red}5.13 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1000 entities	$$10.9 \mathrm{ms} \pm 103 \mathrm{μs}\left({\color{gray}2.47 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$11.5 \mathrm{ms} \pm 107 \mathrm{μs}\left({\color{gray}4.77 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity

Function	Value	Mean	Flame graphs
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1	$$11.6 \mathrm{ms} \pm 132 \mathrm{μs}\left({\color{red}6.01 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$11.2 \mathrm{ms} \pm 91.4 \mathrm{μs}\left({\color{gray}2.79 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$12.0 \mathrm{ms} \pm 113 \mathrm{μs}\left({\color{red}9.49 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$11.9 \mathrm{ms} \pm 102 \mathrm{μs}\left({\color{red}9.03 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$11.6 \mathrm{ms} \pm 106 \mathrm{μs}\left({\color{red}5.10 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$11.6 \mathrm{ms} \pm 84.5 \mathrm{μs}\left({\color{gray}4.79 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$11.5 \mathrm{ms} \pm 88.9 \mathrm{μs}\left({\color{gray}3.89 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$11.6 \mathrm{ms} \pm 101 \mathrm{μs}\left({\color{red}5.04 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$11.5 \mathrm{ms} \pm 104 \mathrm{μs}\left({\color{gray}2.73 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity_type

Function	Value	Mean	Flame graphs
get_entity_type_by_id	Account ID: bf5a9ef5-dc3b-43cf-a291-6210c0321eba	$$8.41 \mathrm{ms} \pm 68.3 \mathrm{μs}\left({\color{gray}3.41 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
entity_by_property	traversal_paths=0	0	$$60.5 \mathrm{ms} \pm 580 \mathrm{μs}\left({\color{gray}4.74 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=255	1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true	$$116 \mathrm{ms} \pm 905 \mathrm{μs}\left({\color{gray}0.733 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false	$$64.5 \mathrm{ms} \pm 567 \mathrm{μs}\left({\color{gray}-0.620 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true	$$75.4 \mathrm{ms} \pm 616 \mathrm{μs}\left({\color{gray}2.54 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true	$$87.2 \mathrm{ms} \pm 742 \mathrm{μs}\left({\color{gray}-1.395 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true	$$93.3 \mathrm{ms} \pm 713 \mathrm{μs}\left({\color{gray}0.616 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=0	0	$$49.4 \mathrm{ms} \pm 407 \mathrm{μs}\left({\color{gray}0.286 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=255	1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true	$$76.7 \mathrm{ms} \pm 603 \mathrm{μs}\left({\color{gray}-1.240 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false	$$55.9 \mathrm{ms} \pm 506 \mathrm{μs}\left({\color{gray}-1.387 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true	$$64.6 \mathrm{ms} \pm 565 \mathrm{μs}\left({\color{gray}-1.378 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true	$$66.2 \mathrm{ms} \pm 592 \mathrm{μs}\left({\color{gray}-1.002 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true	$$65.8 \mathrm{ms} \pm 543 \mathrm{μs}\left({\color{gray}-2.377 \mathrm{\%}}\right) $$

scenarios

Function	Value	Mean	Flame graphs
full_test	query-limited	$$125 \mathrm{ms} \pm 886 \mathrm{μs}\left({\color{red}5.46 \mathrm{\%}}\right) $$	Flame Graph
full_test	query-unlimited	$$135 \mathrm{ms} \pm 1.05 \mathrm{ms}\left({\color{gray}3.30 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-limited	$$24.7 \mathrm{ms} \pm 205 \mathrm{μs}\left({\color{gray}4.33 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-unlimited	$$531 \mathrm{ms} \pm 1.64 \mathrm{ms}\left({\color{gray}0.157 \mathrm{\%}}\right) $$	Flame Graph

[indietyp]

superseded by a set of PRs that properly implement it