Port to TypeScript

[mthadley]

Rationale

WorkOS is a TypeScript-centric engineering organization. Most of our stack runs on TypeScript with all engineers having strong proficiency with the language. Pgslice was originally written in Ruby (for which many of us have a strong affinity for, myself included), which presents several challenges:

• Customizations to Pgslice (which we've already made) become harder to make and review, as Ruby expertise is not as prevalent.
• Invoking pgslice means needing to have a Ruby interpreter available, complicating environments, and increasing our surface area for auditing/making (e.g. making sure we are running supported Ruby versions, gems, etc.)
• Ruby pgslice only exposes a CLI tool, whereas in certain contexts we'd like the option to also invoke it as a TypeScript library, without needing to go through any kind of CLI wrapper, or parsing IO streams.

So porting pgslice to TypeScript makes contributions from our team easier, reduces maintenance overhead for our foundation team, and lets us integrate more directly for future automations.

Feasibility

Is it feasible or rationale to port a tool like pgslice? It's been done before, albeit in the form of an experimental Go package. But we think so.

pgslice is a fairly straightforward tool to port. The code is relatively small (on the order of 1k LOC), easy to read, and well-documented. With today's modern LLM tooling, we can lean heavily on them to do the grunt work of the porting, after we lay a strong foundation.

Finally, one of the great things about Ruby is its flexibility, allowing us to re-use the existing tests as a regression suite to help guide the porting process.

Porting Process

The full commit history is available below. As you'll notice Claude Opus 4.5 was the primary model uses, and I ensured that whenever it was used I committed its results in entirety, with attribution, and its own summary of the changes. Changes that I made "the old fashioned way" are delineated by having no attribution (Co-authored-by).

I broke the porting process down into phases:

Research and Planning

First, I documented the porting philosophy into a hand-written CLAUDE.md. You can see where I started and ended, iterating as I found recurring errors in the agent-assisted changes. Important notes were things like how to run the Ruby tests, or which features to not port (more on that later).

Key dependencies were chosen by my own research. slonik due to my own awareness and that it presented a nicer interface around the low-level pg package, which we already use. clipanion due to its superficial likeness to thor from the Ruby world, in hopes of making command-porting more straightforward.

Lay the Foundation

Before letting the AI loose, I focused on laying the foundation of the package itself. This went through several iterations, but you can see examples:

• Basic structure of a command.
• Test scaffolding

Agent-assisted Command Porting

Finally, I used Claude to port each command, one-by-one in separate sessions, cleaning up and abstracting after each go. Examples:

• prep
• add_partitions
• enable_mirroring
• fill

As more commands were ported (and I continued to refactor in between), the agent-assisted porting got both faster and better.

Results

By the end, it was possible to run USE_TYPESCRIPT_PORT=1 rake test and have the entire suite pass, minus a few tests that were intentionally skipped.

Regression Test Output

$ USE_TYPESCRIPT_PORT=1 bundle exec rake test TESTOPTS="-v"
/Users/michael.hadley/projects/workos/pgslice/test/pgslice_test.rb:401: warning: ambiguity between regexp and two divisions: wrap regexp in parentheses or add a space after `/' operator
/Users/michael.hadley/projects/workos/pgslice/test/pgslice_test.rb:427: warning: ambiguity between regexp and two divisions: wrap regexp in parentheses or add a space after `/' operator
/Users/michael.hadley/projects/workos/pgslice/test/pgslice_test.rb:435: warning: ambiguity between regexp and two divisions: wrap regexp in parentheses or add a space after `/' operator
/Users/michael.hadley/projects/workos/pgslice/test/pgslice_test.rb:463: warning: ambiguity between regexp and two divisions: wrap regexp in parentheses or add a space after `/' operator
Run options: -v --seed 8197

# Running:

PgSliceTest#test_ulid_no_partition = 2.87 s = .
PgSliceTest#test_add_partitions_negative_past = 0.25 s = .
PgSliceTest#test_prep_no_partition_trigger_based = 0.04 s = S
PgSliceTest#test_prep_invalid_period = 0.12 s = .
PgSliceTest#test_unprep_missing_table = 0.14 s = .
PgSliceTest#test_month = 1.43 s = .
PgSliceTest#test_v2 = 0.03 s = S
PgSliceTest#test_unswap_missing_table = 0.14 s = .
PgSliceTest#test_synchronize_missing_table = 0.14 s = .
PgSliceTest#test_analyze_missing_table = 0.15 s = .
PgSliceTest#test_disable_mirroring_missing_table = 0.14 s = .
PgSliceTest#test_synchronize = 0.60 s = .
PgSliceTest#test_enable_mirroring_missing_intermediate_table = 0.15 s = .
PgSliceTest#test_add_partitions_missing_tablespace = 0.28 s = .
PgSliceTest#test_enable_retired_mirroring_missing_table = 0.15 s = .
PgSliceTest#test_day = 1.51 s = .
PgSliceTest#test_disable_retired_mirroring_missing_table = 0.15 s = .
PgSliceTest#test_enable_retired_mirroring = 0.95 s = .
PgSliceTest#test_add_partitions_missing_table = 0.15 s = .
PgSliceTest#test_prep_no_partition_extra_arguments = 0.14 s = .
PgSliceTest#test_tablespace = 1.44 s = .
PgSliceTest#test_prep_missing_table = 0.16 s = .
PgSliceTest#test_year = 1.43 s = .
PgSliceTest#test_fill_missing_table = 0.15 s = .
PgSliceTest#test_enable_mirroring = 0.28 s = .
PgSliceTest#test_no_partition = 0.98 s = .
PgSliceTest#test_disable_retired_mirroring = 1.09 s = .
PgSliceTest#test_mirroring_triggers_work = 0.42 s = .
PgSliceTest#test_timestamptz = 1.43 s = .
PgSliceTest#test_trigger_based = 0.03 s = S
PgSliceTest#test_prep_missing_column = 0.16 s = .
PgSliceTest#test_tablespace_trigger_based = 0.03 s = S
PgSliceTest#test_ulid_fill_swapped = 3.50 s = .
PgSliceTest#test_prep_missing_arguments = 0.14 s = .
PgSliceTest#test_ulid_fill_with_start = 2.60 s = .
PgSliceTest#test_add_partitions_negative_future = 0.24 s = .
PgSliceTest#test_trigger_based_timestamptz = 0.04 s = S
PgSliceTest#test_disable_mirroring = 0.40 s = .
PgSliceTest#test_ulid_partitioned = 2.84 s = .
PgSliceTest#test_swap_missing_table = 0.15 s = .
PgSliceTest#test_swap_creates_retired_mirroring_trigger = 0.71 s = .
PgSliceTest#test_date = 1.45 s = .
PgSliceTest#test_enable_mirroring_missing_table = 0.14 s = .
PgSliceTest#test_add_partitions_non_partitioned_table = 0.15 s = .
PgSliceTest#test_ulid_numeric_still_works = 0.57 s = .

Fabulous run in 30.064246s, 1.4968 runs/s, 17.1965 assertions/s.

  1) Skipped:
PgSliceTest#test_prep_no_partition_trigger_based [test/pgslice_test.rb:101]:
TypeScript port doesn't support trigger-based partitioning

  2) Skipped:
PgSliceTest#test_v2 [test/pgslice_test.rb:67]:
TypeScript port doesn't support v2 partitioning

  3) Skipped:
PgSliceTest#test_trigger_based [test/pgslice_test.rb:57]:
TypeScript port doesn't support trigger-based partitioning

  4) Skipped:
PgSliceTest#test_tablespace_trigger_based [test/pgslice_test.rb:76]:
TypeScript port doesn't support trigger-based partitioning

  5) Skipped:
PgSliceTest#test_trigger_based_timestamptz [test/pgslice_test.rb:62]:
TypeScript port doesn't support trigger-based partitioning

45 runs, 517 assertions, 0 failures, 0 errors, 5 skips

Test coverage is generally more extensive and fine-grained than the original Ruby port.

Differences

As alluded to earlier, there are some differences between the Ruby and TypeScript versions, given the port is targeted at WorkOS needs.

• The port does not support "trigger-based" partitioning. WorkOS uses modern versions of Postgres that support "declarative" partitioning.
• The port does not support "v2" of pgslice, meaning it cannot be used against tables that were partitioned by older versions of pgslice.
• The port does not support compound primary keys. The original Ruby version had some support, but not all commands handled them, and some seemed to even have bugs (only factoring in part of a compound key). WorkOS does not need compound key support, so it was removed.
• Various command line flags were removed. These were untested (e.g. fill --where "some_condition") and we weren't planning on using anyways.