Adam Cameron's Dev Blog

Setting up dev/prod environments with Lovable and Supabase

2026-01-22T23:14:00.001+00:00

G'day:

This is one of those "we really should have done this from the start" situations that catches up with you eventually.

We've been building an e-commerce admin application using Lovable (an AI coding platform that generates React/TypeScript apps with Supabase backends). For context, Lovable is one of those tools where you describe what you want in natural language (vibe-coding [muttermutter]), and it generates working code with database migrations and everything. Works surprisingly well, actually.

The problem: we'd been developing everything directly in what would eventually become the production environment. Single Supabase instance, no separation between dev work and live system. Every code change, every database migration, every "let's try this and see what happens" experiment - all happening in the same environment that would eventually serve real users.

This is fine when you're prototyping. It's less fine when the Product Owner has been merging features over the Christmas break and you've suddenly got 9 pull requests to audit before you can safely call anything "production ready".

Time to sort out proper dev/test/prod environments. How hard could it be?

The single environment problem

Before we get into the solution, let's be clear about what was wrong with the setup.

We had one Supabase project. Everything happened there:

Development work from Lovable
Database migrations as they were generated
Test data mixed with what would eventually be real data
Edge functions being deployed and redeployed
Configuration secrets that would need to be different in production

The workflow was: make changes in Lovable, push to GitHub, review the PR, merge. Rinse and repeat. No smoke testing in a separate environment, no way to verify migrations wouldn't break things, no safety net.

This meant we couldn't safely experiment. Every "what if we tried this approach?" question carried the risk of breaking the only database we had. And with a small team, there's no coordination between what one person is working on and what another person might be testing.

The obvious solution: separate Supabase instances for dev and prod, with proper deployment workflows between them. Standard stuff, really. Except Lovable's documentation barely mentions this scenario, and Supabase has some non-obvious behaviours around how environment separation actually works.

Lovable Cloud: the auto-provisioning disaster

We'd actually tried to set up separate environments once before, and it went spectacularly wrong.

The plan was simple: create a new Lovable project, connect it to our existing Supabase instance, start building features. Lovable has an option to use an external Supabase project rather than having Lovable manage everything, so we configured that upfront.

Except before we could do any actual work, Lovable forced us to enable "Lovable Cloud". This wasn't presented as optional - it was a "you must do this to proceed" situation. Fair enough, we thought, probably just some hosting infrastructure it needs.

Wrong.

Enabling Lovable Cloud auto-provisioned a completely different Supabase instance and ignored our pre-configured external connection entirely. Login attempts started failing with HTTP 400 errors because the frontend was trying to authenticate against the wrong database. The browser console showed requests going to cfjdkppbukvajhaqmoon.supabase.co when we'd explicitly configured it to use twvzqadjueqejcsrtaed.supabase.co.

It turns out Lovable has two completely different modes:

Lovable Cloud - auto-provisions its own Supabase, manages everything, cannot be overridden
External Supabase - you bring your own Supabase project and manage it yourself

Once Cloud mode is enabled, it completely overrides any external connections even if you'd explicitly configured them first. This isn't documented clearly in the Lovable UI - you just get a toggle that seems like it's enabling some hosting feature, not fundamentally changing how the entire project works.

The fix: delete the project entirely and start again with explicit "DO NOT enable Cloud" instructions from the beginning. Not ideal, but it worked.

Understanding the pieces

Once we'd learned our lesson about Lovable Cloud, we needed to properly understand how environment separation actually works with this stack.

The key insight came from an article by someone who'd already solved this problem: Lovable Branching. Their approach was straightforward:

DEV: Lovable project → dev GitHub branch → DEV Supabase instance → Lovable hosting
PROD: Same repo → main GitHub branch → PROD Supabase instance → Netlify hosting

The critical bit: completely separate Supabase instances. Not Supabase's branching feature (which exists but is more for preview environments), actual separate projects. One for development, one for production, zero overlap.

This makes sense when you think about it. Database migrations aren't like code - you can't just merge them and hope for the best. You need to test them in isolation before running them against production data. Separate instances means you can experiment freely in dev without any risk of accidentally breaking prod.

Environment variables in three different contexts

Where things get interesting is environment variables. Turns out there are three completely different systems at play:

Frontend variables (Vite): These need the VITE_ prefix to be accessible in browser-side code. You access them via import.meta.env.VITE_SUPABASE_URL and similar. The .env file contains your DEV values as defaults, but Netlify's environment variables override these at build time for production. This inheritance is standard Vite behaviour - actual environment variables take precedence over .env file values.

Edge function variables (Deno): These are managed through Supabase's "Edge Function Secrets" system. You set them via supabase secrets set KEY=value or through the Supabase dashboard, and they're accessed in code via Deno.env.get('KEY'). Here's the odd bit: Supabase treats all edge function environment variables as "secrets" regardless of whether they're actually sensitive. Non-secret configuration like API hostnames still goes through the secrets mechanism. It's just how Supabase works. This triggered my "someone is wrong on the internet" inclinations, and I found (well: OK, Claudia found it whilst diagnosing the issue) a GitHub issue about it: Upload non-secret environment variables to Edge Function Secrets Management. Upvoted. I notice now that someone at Supabase has noted said issue, shortly after I nudged it.

CLI configuration (Supabase tooling): When you run npx supabase link --project-ref <PROJECT_ID>, it writes the project reference to supabase/.temp/project-ref. This is local state that determines which Supabase instance the CLI commands operate against. The .temp directory is gitignored, so each developer (and each environment) can link to different projects without conflicts.

The important realisation: these three systems don't talk to each other. Your frontend env vars in .env are separate from your edge function secrets in Supabase, which are separate from your local CLI link state. They all happen to reference the same Supabase projects, but through completely independent configuration mechanisms.

The VITE_SUPABASE_PROJECT_ID battle

This is where things got properly frustrating.

The Supabase client needs two things to initialise: the project URL and the publishable key. That's it. The project ID is already embedded in the URL - https://twvzqadjueqejcsrtaed.supabase.co contains the ID right there in the subdomain. Having a separate VITE_SUPABASE_PROJECT_ID variable is completely redundant.

So we asked Lovable to remove it from the .env file.

Every. Single. Commit. It put it back.

We tried being explicit: "We don't use VITE_SUPABASE_PROJECT_ID, please remove it". Lovable responded "Yes, done" and left it there. We manually deleted it and pushed the change ourselves. The next commit from Lovable put it back. We explained why it was redundant. Lovable agreed with the reasoning, confirmed it would remove the variable, and then didn't.

The AI clearly didn't understand why it kept adding this variable back. It wasn't being defiant - it genuinely seemed to think it was helping. But no amount of prompting, explaining, or manual removal could break the pattern.

Claudia (my AI pair programmer, who was observing this farce) found it hilarious. I found it less hilarious. In the end, I did something rare: I surrendered. The variable is still in the codebase. It doesn't do anything, the Supabase client doesn't use it, but it's there. Lovable won.

This became a useful lesson about AI code generation tools: they're brilliant at generating the initial 80% of a solution, but that last 20% - the refinement, the cleanup, the removal of unnecessary cruft - sometimes requires human intervention that the AI just can't process. Even when it claims to understand.

The review workflow

Speaking of that 80/20 split, we developed a proper review process for Lovable-generated code. This wasn't just paranoia - AI-generated code needs human oversight, especially when it's going to production.

The workflow went like this:

Lovable generates code based on a prompt from the Product Owner
I creates a pull request from the feature branch to dev
GitHub Copilot does an automated review, catching obvious issues
I review the code manually, looking for security concerns, deployment gotchas, architectural problems
Claudia reviews it as well, often catching things I missed
We compile a comprehensive list of issues and create a fix prompt for Lovable
Lovable makes another pass, addressing the feedback
Repeat until the code is actually mergeable

This multi-layer review caught things that no single reviewer would spot. Copilot is good at identifying code smells and standard issues. I'm good at spotting deployment risks and security problems. Claudia is good at catching logical inconsistencies and suggesting better patterns.

And, full disclosure: I can read TypeScript and React code, and having spent a few solid weeks doing "self-teaching" on both - I should blog this actually - I understand what's going on for the most part, but I am not a TS/React dev. I need Claudia and Copilot to review this stuff.

One recurring annoyance: GitHub Copilot's automated review insists on suggesting American spellings. "Initialize" instead of "initialise", "color" instead of "colour". Every. Single. Review. I'm a Kiwi, and a civilised person, and this is an app for a UK audience: the codebase uses British English not that tariff-addled colonial shite, but Copilot is having none of it.

The key insight here is that AI code generation isn't "press button, receive working code". It's more like working with a very knowledgeable but inexperienced junior developer who needs guidance on architecture, security, and project-specific patterns. The review process is where the actual quality control happens.

The actual working solution

After all the false starts and battles with Lovable's helpful tendencies, here's what actually works.

The architecture

DEV environment:

Supabase project: the original instance we'd been using all along
GitHub branches: DEV for integration, and each ticket's work is done in a short-lived feature branch of DEV, eg JRA-1234_remove_project_id_AGAIN
Hosting: Lovable's built-in preview hosting (good enough for dev work)
Database: DEV Supabase instance with all our test data and experimental migrations

PROD environment:

Supabase project: fresh instance created specifically for production
GitHub branch: main only
Hosting: Netlify (automatic deployment on push to main)
Database: PROD Supabase instance with clean migration history

The decision to keep the original instance as DEV rather than promoting it to PROD was deliberate. The existing instance had all our development history, test data, and the occasional experimental schema change. Starting PROD fresh from a clean set of migrations gave us a proper foundation without any cruft.

The deployment process

Frontend deployment happens automatically via Netlify. When code merges to main, Netlify detects the change, runs npm ci followed by npm run build, and serves the static files from the dist folder. Environment variables configured in Netlify's UI override the .env file defaults, giving us PROD Supabase credentials without changing any code.

Backend deployment is deliberately manual. No automation, no automatic deploys on merge, no clever CI/CD pipelines. When we're ready to deploy database changes to production:

npx supabase login
npx supabase link --project-ref <PROD_PROJECT_ID>
npx supabase db push
npx supabase functions deploy

That's it. Four commands, run by a human, who has presumably read the migrations and understood what they're about to do. The db push command reads all migration files from supabase/migrations/ and applies any that haven't been run yet, tracked via the supabase_migrations.schema_migrations table.

This manual approach is a deliberate choice. Database migrations can break things in ways that frontend code changes usually don't. Having a human in the loop - someone who's actually reviewed the SQL and thought about what could go wrong - provides a safety net that automated deployments don't.

And, to be transparent, we are a very small team, and I am a Team Lead / Developer by trade, and all this "systems config shite" is a) beyond me; b) of very little interest to me. I'm doing it because "someone has to do it" (cue: sympathetic violins). I know we should have some sort of CI/CD going on, and eventually we will, but we don't need it for MVP, so I'm managing it manually for now. And - as per above - it's dead easy!

Oh, one thing I didn't mention is this is precisely how I finishes strumming-up the new Supabase instance for prod. Obviously the new Supabase DB was empty... I just did the db push and functions deploy to get it up to date with dev.

Keeping branches in sync

Between tasks, we merge main back to dev to keep them in sync. This prevents the two branches from drifting too far apart and makes the eventual dev → main merges simpler. Standard Git workflow stuff, but worth stating explicitly because Lovable's documentation focuses almost entirely on the "single branch, continuous deployment" model.

Edge functions and secrets

Edge functions turned out to be simpler than expected, once we understood how Supabase handles them.

The functions themselves live in supabase/functions/ in the same repository as everything else. They're not a separate codebase or deployment - they're just TypeScript files that get deployed via npx supabase functions deploy. When you push changes to GitHub, Supabase doesn't automatically deploy them (unlike the frontend with Netlify). You need to explicitly run the deploy command.

Environment variables for edge functions work through Supabase's "Edge Function Secrets" system. Some are auto-managed by Supabase itself:

SUPABASE_URL
SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
SUPABASE_DB_URL

These automatically have the correct values for whichever Supabase instance is running the function. DEV Supabase runs the function, it gets DEV credentials. PROD Supabase runs the function, it gets PROD credentials. No configuration needed.

Any other environment variables need to be set manually per environment. For our project, this included:

EMAIL_API_KEY - for sending emails
BANK_API_ACCESS_TOKEN - for our bank's API integration
BANK_API_WEBHOOK_SECRET - webhook signature verification
BANK_API_HOST - the API hostname (different for sandbox vs production)

That last one is worth noting: we needed BANK_API_HOST to be api-test.ourbank.com in DEV and api.ourbank.com in PROD. This isn't a secret - it's just configuration. But Supabase treats all edge function environment variables as "secrets" regardless of whether they're actually sensitive.

You set these via the Supabase dashboard (Authentication → Secrets) or via the CLI:

npx supabase secrets set BANK_API_HOST=api.ourbank.com

One gotcha: you can't view the raw values of secrets in the dashboard after they're set, only their hash. This is annoying for non-sensitive configuration values where you might want to verify what's actually configured. But it's a one-time setup per environment, so not a huge problem in practice. And there is that GitHub issue…

This is then used in our edge function along these lines:

function getOurBankApiUrl(): string {
  const apiHost = Deno.env.get('BANK_API_HOST');
  if (!apiHost) {
    throw new Error(
      'Missing bank configuration. ' +
      'Set BANK_API_HOST environment variable.'
    );
  }
  return `https://${apiHost}/some_slug_here`;
}

JWT verification settings

Edge functions by default require valid Supabase JWTs in the Authorization header. For webhooks (or other computer-to-computer calls) or public endpoints, you need to disable this. This goes in supabase/config.toml:

[functions.ourbank-webhook]
verify_jwt = false

[functions.validate-bank-details]
verify_jwt = false

This is the only thing that should be in your config.toml. We initially had 60+ lines of local development server configuration (API ports, database settings, auth config) that Lovable had generated. All unnecessary - that configuration is for running Supabase locally, which we're not doing. The JWT settings are needed because npx supabase functions deploy falls back to these values.

Gotchas and non-obvious behaviours

Here's everything that wasn't obvious from the documentation, discovered through trial and error.

Supabase CLI tool location changed

Older documentation references a .supabase/ directory for CLI state. The CLI now uses supabase/.temp/ instead. When you run npx supabase link, it writes the project reference to supabase/.temp/project-ref, along with version tracking files and connection details.

This directory must be in .gitignore because it's environment-specific. Each developer links to their own preferred project (DEV or PROD), and these link states are stored locally. The directory structure looks like:

supabase/
├── .temp/
│   ├── project-ref          # Linked project ID
│   ├── storage-version      # Version tracking
│   ├── rest-version
│   ├── gotrue-version
│   ├── postgres-version
│   ├── pooler-url          # Connection pooler URL
│   └── cli-latest          # CLI version check
├── functions/              # Edge functions
├── migrations/             # SQL migration files
└── config.toml            # JWT settings only

The "PRODUCTION" badge means nothing

Every Supabase project shows a "PRODUCTION" badge in the dashboard header. This isn't an indicator of whether your project is actually being used for production - it's Supabase's terminology for distinguishing standalone projects from preview branches created via their branching feature. Your DEV instance will show "PRODUCTION" just like your actual production instance. Ignore it.

npx is not npm install -g

This is just me not being a Node dev.

Running npm install -g supabase returns a warning: "Installing Supabase CLI as a global module is not supported." Instead, use npx supabase <command> for everything. This downloads the CLI on-demand, caches it in npm's global cache, and executes it. It's not "installed" in the traditional sense, but it works identically from a user perspective.

First-time use requires npx supabase login which opens a browser for OAuth authentication. This stores an access token locally. Without this, CLI commands fail with "Access token not provided".

Netlify build doesn't touch the database

Common confusion: when Netlify runs npm run build, it only compiles frontend code to static files. It does not run database migrations. Those are a completely separate manual step via npx supabase db push.

This separation is deliberate - frontend and backend deploy independently. You can deploy backend changes without touching the frontend, and vice versa. The deployment order matters though: always deploy backend schema changes first, then frontend code that depends on those changes.

React Router and direct navigation

Our first production bug was a proper head-scratcher. Direct navigation to https://ourapp.netlify.app/products returned a 404, but clicking through from the home page worked fine.

Turns out this is a fundamental disconnect (for me!) between how React Router works and what servers expect. React apps are Single Page Applications - there's literally one HTML file (index.html). React Router handles navigation by swapping components in JavaScript, updating the browser's address bar without making server requests.

When you click a link inside the app (like from / to /products), React Router intercepts it and just changes what's rendered. No server request happens. But when you directly navigate to /products in a fresh browser tab, Netlify's server receives a request for /products, looks for a file called products.html, can't find it, and returns 404.

I'll be honest - this felt like broken behaviour to me. Surely "being able to navigate to any page directly" is web application table stakes? How is this not just working? But the issue is that React and React Router are client-side libraries. They have no control over what the server does. The server needs explicit configuration to serve index.html for all routes. I felt a bit thick when Claudia explained this to me using small words.

The fix is simple: create public/_redirects with one line:

/* /index.html 200

This tells Netlify: for any URL path, serve index.html instead of looking for specific files. The 200 status code means it's a rewrite, not a redirect - the browser URL stays as /products but Netlify serves index.html behind the scenes. React boots up, React Router sees the URL, and renders the correct page.

Why didn't we hit this during development? Because Vite (the dev server) already has this behaviour built in. It knows you're building an SPA and handles it automatically. The problem only appears when you deploy to a production server that doesn't know about your client-side routing.

This should probably be included by default in any SPA scaffolding tool, but it's not. Add it to your "first deploy checklist" and move on.

Environment variable override precedence

Vite's environment variable resolution: actual environment variables (set in Netlify's UI) override .env file values at build time. The .env file serves as the fallback for local development. This means you can commit DEV credentials in .env, and Netlify will use PROD credentials from its configuration without any code changes.

Migration file format matters

Supabase requires migration files to use timestamp format: YYYYMMDDHHMMSS_description.sql. Lovable doesn't use this format by default. You need to explicitly instruct it in your Lovable Knowledge file, and even then it sometimes needs reinforcement in prompts. We added this to our Knowledge file:

Database migrations use timestamp format: YYYYMMDDHHMMSS_description.sql
Create a migration file for EVERY database change (tables, columns, indexes, constraints, RLS policies, functions, triggers)
Never make database changes without generating a corresponding migration file

Even with this, Lovable occasionally forgets, or will use a GUID in place of the description. Code review catches it.

Supabase key format evolution

Supabase has two key formats in the wild:

Legacy anon public key (JWT format): rlWuoTpv...
New publishable key format: sb_publishable_...

Both work, but the dashboard now recommends using publishable keys. We're using the legacy JWT format for now because both our DEV and PROD instances started with it, and mixing formats between environments seemed like asking for trouble. Migration to the new format is a separate ticket for when we're not in the middle of setting up production.

What we ended up with

After all the false starts, surrenders to Lovable's stubbornness, and discoveries about how these tools actually work, we've got a functioning dev/prod separation that's simple enough to be maintainable.

The key decisions that made it work:

Separate Supabase instances rather than using branching features - complete isolation, no data leakage risk
Manual database deployments rather than automation - deliberate, reviewed, controlled
Short-lived feature branches off a long-lived dev branch - standard Git workflow that the team already understands
Netlify for frontend hosting with environment variable overrides - zero-config deployment that just works
Multi-layer code review process - Copilot for automated checks, me for architecture and security, Claudia for catching the bits I miss

The workflow is straightforward: develop in Lovable against DEV, review the pull request, merge to dev, smoke test, merge dev to main when ready, manually deploy backend changes, let Netlify handle the frontend. It's not fancy, there's no sophisticated CI/CD pipeline, but it's appropriate for a small team building an MVP.

The biggest lesson: AI code generation tools like Lovable are brilliant at the initial 80% of implementation, but that last 20% - the refinement, security review, deployment considerations - still needs human oversight. A technically proficient human. The review workflow isn't overhead; it's where the actual quality control happens.

Don't get sucked into the hype: "vibe coding" is simply not a thing when it comes to production applications. It's only good for building functional demos.

And sometimes, you just have to accept that VITE_SUPABASE_PROJECT_ID is going to live in your codebase forever, doing absolutely nothing, because Lovable has decided it belongs there and no amount of reasoning will change its mind.

Righto.

--
Adam

P.S. As well as doing all the Netlify config for PROD, I also set up a separate Netlify site for TEST. This one triggers builds off merges to dev and uses the DEV Supabase credentials. It's exposed to the world on the admin-test subdomain (live is just admin). This gives the Product Owner a stable environment to test new features before they go live, running in the same hosting setup as production but against the dev database. Means we can catch UI issues or integration problems in a production-like environment without risking actual production.

Lovable and its seemingly self-defeating pricing and business model

2025-12-12T13:58:00.001+00:00

G'day:

Sigh. I watched a video about Lovable the other day, which in and of itself was entirely adequate, and provided some interesting information in that way that one paragraph of text could also provide (such is the way with YT technical videos sometimes). It's this one: Master Lovable AI in 20 Minutes (NEW 2.0 UPDATE).

One of the tactics the author detailed was this thing in Lovable that - despite it being an AI-driven app generator thingey (you know "vibe coding" etc), the standard approach to things seems to be to use someone else's AI tooling to do most of the planning / AI / back-and-forth work, and then get - eg - ChatGPT to summarise the plan as a "prompt" which one then gives to the Lovable AI, and it churns away and will generate a prototype-quality app that follows most of the guidance, but still grafts on a sixth finger (sic) here and there because well: AI. At the time I was bemused as to why one would use another AI tool to do the planning, instead of using Lovable itself.

So I asked the question in the video comments:

@darrelwilson I was kinda perplexed as to why it was necessary to use one AI to draft guidance for another AI? I realise this ecosystem is fast moving, but looking today Lovable is using Opus 4.5, which should be on a "cognitive" par with ChatGPT's LLM... so what's the difference between prompting ChatGPT as an intermediary over just prompting Lovable in the first place? Is this mostly to game token-usage on Lovable? Or is it to keep Lovable's memory-context tight & not cluttered with intermediary discussions with ChatGPT whilst drafting the "ideal" prompt? Keeping zeitgeisty, I asked Claude Desktop's Opus 4.5 why one might do this, and its reaction was bemusement, as it seems like an unnecessary step..?

Someone replied:

@adamcameron1 I mean you should really read the prompt GPT provides. If you put a generic prompt into Lovable directly youll have less control & say into what it builds. Its going to extroplate if you aren't specific.

That didn't quite land with me, so I followed-up:

Hi @shenshaw5345, I appreciate the response, cheers!

Reasoning about this, I'd expect one would not charge in and go "build an app! Oh... no, hang on... not like that. Do it this way... damn, still not right... oh maaaan, this is never gonna work"; one would do precisely what was done in this example via ChatGPT first, and "discuss" with Lovable what needs building before any code is written. Once one reckons everyone is on the same page with the plan, get Lovable to spit out the plan, review (poss rinse and repeat), and then go "OK build that". Not all chat prompts need to result in code being written, right?

NB: I'm only evaluating the possibilities of Lovable as yet - this is part of the evaluation - so I am, admittedly, speculating (based on ChatGPT, GitHub Copilot and claude.ai all working this way). Then again, I also know that one has to be direct with AI IDE integrations and prompt it "we are currently just planning, do not write any code until we agree on a plan and I tell you to crack on with it". I'm presuming Lovable works the same, given it's the same underlying AI models...

THAT SAID, I just checked Lovable's pricing, and it's *ludicrous*... 100 tokens for $25 for a MONTH (as an example; there are better price points than that, obvs). One could burn most of those tokens in a planning session for one app component! Compare that to Claude.ai which measures its tokens by the million for similar amounts of $$$. Obvs not directly analogous, but honestly, Lovable seems to have missed a trick here: it's important to have the chat as part of the context for the work an agent does. A lot of that is being lost to ChatGPT's context in this case. And a summary of a chat from one AI to another is not the same as the nuance of the actual chat.

This, however, explains why one ought not plan using Lovable. They've hamstrung their offering with their pricing. Duly noted.

Thanks again!

And someone else came back to me:

@adamcameron1 you might not have an idea fully flushed out in your mind. You braindump into chatgpt and it will organize a precise starter prompt for lovable to start. Then u iterate off that. In the AI world, you want to have to starting point as close as you can get it to the finish line to make things easier. 5 or 10 edits is ok. Try doing 50-100 edits and then you start to run into context window issues….. at least that how I assume lovable works.. just started lovable a couple days ago, but i have a good understanding on how prompting affects LLMs

This respondent didn't quite get what I was meaning, so I followed up. And this leads to the reason I am reposting this here:

Hi @youcanfindrace. It might be that. But given I've been working almost exclusively via various AI tooling for the bulk of the year this year; and for about 50% of my work time last year, I'm not so sure I'm misunderstanding how it all comes together. But it's possible, sure.

What I rather more think is that I wasn't as clear as I could have been previously, and my point didn't land with you. Let me change a few things around, and try to be clearer.

Let's pretend the guidance given wasn't "use ChatGPT to build a prompt", but instead "use Claude.ai to build a prompt". You can hopefully see how "using ChatGPT" and "using Claude" are - for most intents - analogous processes: different tools, same job. Like using a DeWalt drill or a Ryobi drill to drill a hole: different sorts of drills, but they're still drills. So we use Claude to build a lovely fully-realised prompt, which we then paste into Lovable's UI... which then uses the same AI as Claude uses to analyse the prompt and perform that action Lovable uses Anthropic's LLMs under the hood (so... same as Claude... same thing... different wrapper, by a different vendor). But even if it's not a wrapper around the same tool, it's still an analogous tool (Lovable=>DeWalt; Claude=>Ryobi) in and of itself. "use a chat with ChatGPT to build a prompt", "use a chat with Claude to build a prompt" and "use a chat with Lovable to build a prompt" are analogous exercises. EXCEPT... that Lovable simply don't facilitate this, because their pricing for their usage tokens are orders of magnitude more than other AI vendors, making it prohibitive to use its AI for... actual AI stuff.

"Building a prompt" is only a tool to transfer the summary of an AI's reasoning between tooling that is otherwise disconnected. For various reasons I sometimes need to have a similar chat with Claude and ChatGPT (or Gemini), and the way to "get the other AI up to speed", is to ask the initial AI "can you please summarise this so I can give it to Gemini and see what they think". One only builds a prompt when doing this context-interchange. However these summaries always lose context and nuance from the underlying chat (think Cliff's Notes vs the actual novel the notes are summarising). In application building, that context/nuance is really important.

Given Lovable uses Anthropic's LLMs, the process in a well-realised application would be to use the Chat interface in Lovable to build the instructions for the Agent interface (still Lovable, different part of the same tool) to then go do the code generation - though even that's more ceremony than necessary. Ideally you'd just have the natural back-and-forth in one interface without artificial handoffs between different AI tools.

However I have done further research into this, and have identified the reason for the way it is (well: others have, I'm just parroting it here). It's simply a bad business model on Lovable's part, basically. They're approximately paying retail rates to purchase usage tokens from Anthropic (so: same if you or I have a plan with them to use Claude.ai), and instead of doing something reasonable like tack a margin on to that cost, they present their "credits" as some sort of priceless artifact that can be only used sparingly, and you should be thankful to have any at all; whereas if one was using Claude etc, then they're basically given away. A chat in Claude is allocated 190k tokens. 190000. And - as an example - I've been chatting back and forth for a business day now, and have used 35k in the current chat. And what happens when I use the 190k? It tells me to start another chat. I'm on a $50/month plan I think, and I've never run into a wall with token usage. And these are the same tokens that Lovable are using under the hood. There's not a one-to-one measure between what Anthropic terms as a token and what Lovable terms a credit, but the disparity is orders of magnitude. Lovable have priced themselves out of the market for their users to be able to use their tool as it ought to be intended.

That's why the ChatGPT-as-intermediary workflow exists.

And the comment was promptly deleted. I dunno if it was by YT's bots, or by the bloke who did the video: there was no explanantion. I changed a few things (in case I was being a meany without noticing), and it was... deleted again. I finally posted a kinda "shrug" response, in the hope that the person I was trying to reply to would see that I did value their feedback to me:

@youcanfindrace Not entirely sure why my reply to you keeps getting deleted: there was nothing code-of-conduct-tripping about it. Poss cos I said something that was not completely in agreement about how wonderful Lovable is, based on research I did into its pricing. But I answered my own question in the process anyhow, so... job done. Soz I couldn't post it here. [eyeroll].

At time of writing, that reply is still there.

Anyhoo, I'm not gonna take the time to do that research (largely googling, reading reddit / stackoverflow, and asking Claude and Gemini) and writing it up only to have it deleted. So I'm reproducing it here where I own it.

And that's that.

Righto.

--
Adam

TypeScript: any, unknown, never

2025-10-10T19:05:00.002+00:00

G'day:

I've been using any and unknown in TypeScript for a while now - enough to know that ESLint hates one and tolerates the other, and that sometimes you need to do x as unknown as y to make the compiler shut up. But knowing they exist and actually understanding what they're for are different things.

The Jira ticket I set up for this was straightforward enough:

Both unknown and any represent values of uncertain type, but they have different safety guarantees. any opts out of type checking entirely, while unknown is type-safe and requires narrowing before use.

Simple, right? any turns off TypeScript's safety checks, unknown keeps them on. I built some examples, wrote some tests, and thought I was done.

Then Claudia pointed out I'd completely missed the point of type narrowing. I was using type assertions (value as string) instead of type guards (actually checking what the value is at runtime). Assertions just tell TypeScript to trust you. Guards actually verify you're right.

Turns out there's a difference between "making the compiler happy" and "writing safe code".

any - when you genuinely don't know or don't care

I started with a generic key-value object that could hold anything:

export type WritableValueObject = Record<string, any>
export type ValueObject = Readonly<WritableValueObject>

type keyValue = [string, any]

export function toValueObject(...kv: keyValue[]): ValueObject {
  const vo: WritableValueObject = kv.reduce(
    (valueObject: WritableValueObject, kv: keyValue): ValueObject => {
      valueObject[kv[0]] = kv[1]
      return valueObject
    },
    {} as WritableValueObject
  )
  return vo
}

(from any.ts)

ESLint immediately flags every any with warnings about unsafe assignments and lack of type checking. But this is actually a legitimate use case - I'm building a container that genuinely holds arbitrary values. The whole point is that I don't know what's in there and don't need to.

The Readonly<...> wrapper makes it immutable after creation, which is what you want for a value object. Try to modify it and TypeScript complains about the index signature being readonly. The error message says Readonly<WritableValueObject> instead of just ValueObject because TypeScript helpfully expands type aliases in error messages. Sometimes this is useful (showing you what the type actually is), sometimes it's just verbose.

unknown - the safer alternative that's actually more annoying

The unknown version looks almost identical:

export type WritableValueObject = Record<string, unknown>
export type ValueObject = Readonly<WritableValueObject>

type keyValue = [string, unknown]

export function toValueObject(...kv: keyValue[]): ValueObject {
  const vo: WritableValueObject = kv.reduce(
    (valueObject: WritableValueObject, kv: keyValue): ValueObject => {
      valueObject[kv[0]] = kv[1]
      return valueObject
    },
    {} as WritableValueObject
  )
  return vo
}

(from unknown.ts)

The difference shows up when you try to use the values. With any, you can do whatever you want:

const value = vo.someKey;
const reversed = reverse(value); // Works fine with any

With unknown, TypeScript blocks you:

const value = vo.someKey;
const reversed = reverse(value); // Error: 'value' is of type 'unknown'

My first solution was type assertions:

const reversed = reverse(value as string); // TypeScript: "OK, if you say so"

This compiles. The tests pass. I thought I was done.

Then Claudia pointed out I wasn't actually checking anything - I was just telling TypeScript to trust me. Type assertions are a polite way of saying "shut up, compiler, I know what I'm doing". Which is fine when you genuinely do know, but defeats the point of using unknown in the first place.

Type guards - actually checking instead of just asserting

The proper way to handle unknown is with type guards - runtime checks that prove what type you're dealing with. TypeScript then narrows the type based on those checks.

The simplest is typeof:

const theWhatNow = returnsAsUnknown(input);

if (typeof theWhatNow === 'string') {
  const reversed = reverse(theWhatNow); // TypeScript knows it's a string now
}

(from unknown.test.ts)

Inside the if block, TypeScript knows theWhatNow is a string because the typeof check proved it. Outside that block, it's still unknown.

For objects, use instanceof:

const theWhatNow = returnsAsUnknown(input);

if (theWhatNow instanceof SomeClass) {
  expect(theWhatNow.someMethod('someValue')).toEqual('someValue');
}

And for custom checks, you can write type guard functions with the is predicate:

export class SomeClass {
  someMethod(someValue: unknown): unknown {
    return someValue
  }

  static isValid(value: unknown): value is SomeClass {
    return value instanceof SomeClass
  }
}

(from unknown.ts)

The value is SomeClass return type tells TypeScript that if this function returns true, the value is definitely a SomeClass:

if (SomeClass.isValid(theWhatNow)) {
  expect(theWhatNow.someMethod('someValue')).toEqual('someValue');
}

This is proper type safety - you're checking at runtime, not just asserting at compile time.

Error handling with unknown

The most practical use of unknown is in error handling. Before TypeScript 4.0, everyone wrote:

try {
  throwSomeError('This is an error')
} catch (e) {  // e is implicitly 'any'
  console.log(e.message)  // Hope it's an Error!
}

Now you can (and should) use unknown:

try {
  throwSomeError('This is an error')
} catch (e: unknown) {
  expect(e).toBeInstanceOf(SomeError)
}

(from unknown.test.ts)

Catches can throw anything - not just Error objects. Someone could throw a string, a number, or literally anything. Using unknown forces you to check what you actually caught before using it.

So which one should you use?

Here's the thing though - for my ValueObject use case, unknown is technically safer but practically more annoying. The whole point of a generic key-value store is that you don't know what's in there. Making users narrow types every time they retrieve a value is tedious:

const value = getValueForKey(vo, 'someKey');
if (typeof value === 'string') {
  doSomething(value);
}

versus just:

const value = getValueForKey(vo, 'someKey');
doSomething(value as string);

For a genuinely generic container where you're accepting "no idea what this is" as part of the design, any is the honest choice. You're not pretending to enforce safety on truly dynamic data.

But for error handling, function parameters that could be anything, or situations where you'll actually check the type before using it, unknown is the better option. It forces you to handle the uncertainty explicitly rather than hoping for the best.

never - the type that can't exist

While any and unknown are about values that could be anything, never is about values that can't exist at all. It's the bottom type - nothing can be assigned to it.

The most obvious use is functions that never return:

export function throwAnError(message: string): never {
  throw new Error(message)
}

(from never.ts)

Functions that throw or loop forever return never because they don't return at all. TypeScript uses this to detect unreachable code:

expect(() => {
  throwAnError('an error')
  // "Unreachable code detected."
  const x: string = ''
  void x
}).toThrow('an error')

(from never.test.ts)

The const x line gets flagged because TypeScript knows the previous line never returns control.

Things get more interesting with conditional never:

export function throwsAnErrorIfItIsBad(message: string): boolean | never {
  if (message.toLowerCase().indexOf('bad') !== -1) {
    throw new Error(message)
  }
  return false
}

The return type says "returns a boolean, or never returns at all". TypeScript doesn't flag unreachable code after calling this function because it might actually return normally.

Exhaustiveness checking

The clever use of never is exhaustiveness checking in type narrowing:

export function returnsStringsOrNumbers(
  value: string | number
): string | number {
  if (typeof value === 'string') {
    const valueToReturn = value + ''
    return valueToReturn
  }
  if (typeof value === 'number') {
    const valueToReturn = value * 1
    return valueToReturn
  }
  const valueToReturn = value // TypeScript hints: const valueToReturn: never
  return valueToReturn
}

(from never.ts)

After checking for string and number, TypeScript knows that value can't be anything else, so it infers the type as never. This is TypeScript's way of saying "we've handled all possible cases".

If you tried to call the function with something that wasn't a string or number (like an array cast to unknown then to string), TypeScript won't catch it at compile time because you've lied to the compiler. But at least the never hint shows you've exhausted the legitimate cases.

The actual lesson

I went into this thinking I understood these types well enough - any opts out, unknown is safer, never is for functions that don't return. All true, but missing the point.

The real distinction is between compile-time assertions and runtime checks. Type assertions (as string) tell TypeScript "trust me", but they don't verify anything. Type guards (typeof, instanceof, custom predicates) actually check at runtime.

For genuinely dynamic data like a generic ValueObject, any is the honest choice - you're accepting the lack of type safety as part of the design. For cases where you'll actually verify the type before using it (like error handling), unknown forces you to be explicit about those checks.

And never is TypeScript's way of tracking control flow and exhaustiveness, which is useful when you actually pay attention to what it's telling you.

The code for all this is in the learning-typescript repository, with test examples showing the differences between assertions and guards. Thanks to Claudia for pointing out I was doing type assertions instead of actual type checking - turns out there's a difference between making the compiler happy and writing safe code.

Righto.

--
Adam

Setting up a Python learning environment: Docker, pytest, and ruff

2025-10-06T21:44:00.003+00:00

G'day:

I'm learning Python. Not because I particularly want to, but because my 14-year-old son Zachary has IT homework and I should probably be able to help him with it. I've been a web developer for decades, but Python's never been part of my stack. Time to fix that gap.

This article covers getting a Python learning environment set up from scratch: Docker container with modern tooling, pytest for testing, and ruff for code quality. The goal is to have a proper development environment where I can write code, run tests, and not have things break in stupid ways. Nothing revolutionary here, but documenting it for when I inevitably forget how Python dependency management works six months from now.

The repo's at github.com/adamcameron/learning-python (tag 3.0.2), and I'm tracking this as Jira tickets because that's how my brain works. LP-1 was the Docker setup, LP-2 was the testing and linting toolchain.

Getting Docker sorted

First job was getting a Python container running. I'm not installing Python directly on my Windows machine - everything goes in Docker. This keeps the host clean and makes it easy to blow away and rebuild when something inevitably goes wrong.

I went with uv for dependency management. It's the modern Python tooling that consolidates what used to be pip, virtualenv, and a bunch of other stuff into one fast binary. It's written in Rust, so it's actually quick, and it handles the virtual environment isolation properly.

The docker-compose.yml is straightforward:

services:
    python:
        build:
            context: ..
            dockerfile: docker/python/Dockerfile

        volumes:
            - ..:/usr/src/app
            - venv:/usr/src/app/.venv

        stdin_open: true
        tty: true

volumes:
    venv:

The key bit here is that separate volume for .venv. Without it, you get the same problem as with Node.js - the host's virtual environment conflicts with the container's. Using a named volume keeps the container's dependencies isolated while still letting me edit source files on the host.

The Dockerfile handles the initial setup:

FROM astral/uv:python3.11-bookworm

RUN echo "alias ll='ls -alF'" >> ~/.bashrc
RUN echo "alias cls='clear; printf \"\033[3J\"'" >> ~/.bashrc

RUN ["apt-get", "update"]
RUN ["apt-get", "install", "-y", "vim"]

WORKDIR  /usr/src/app

ENV UV_LINK_MODE=copy

RUN \
    --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync \
    --no-install-project

ENTRYPOINT ["bash"]

Nothing fancy. The astral/uv base image already has Python and uv installed. I'm using Python 3.11 because it's stable and well-supported. The uv sync at build time installs dependencies from pyproject.toml, and that cache mount makes rebuilds faster.

The ENTRYPOINT ["bash"] keeps the container running so I can exec into it and run commands. I'm used to having PHP-FPM containers that stay up with their own service loop, and this achieves the same thing.

One thing I'm doing here differently from usual, is that I am using mount to temporarily expose files to the Docker build process. In the past I would have copied pyproject.toml into the image file system. Why the change? Cos I did't realise I could do this until I saw it in this article I googled up: "Using uv in Docker › Intermediate layers"! I'm gonna use this stragey from now on, I think…

Project configuration and initial code

Python projects use pyproject.toml for configuration - it's the equivalent of package.json in Node.js or composer.json in PHP. Here's the initial setup:

[project]
name = "learning-python"
version = "0.1"
description = "And now I need to learn Python..."
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
howdy = "learningpython.lp2.main:greet"

[build-system]
requires = ["uv_build>=0.8.15,<0.9.0"]
build-backend = "uv_build"

[tool.uv.build-backend]
namespace = true

The project.scripts section defines a howdy command that calls the greet function from learningpython.main. The syntax is module.path:function. This makes the function callable via uv run howdy from the command line.

The namespace = true bit tells uv to use namespace packages, which means I don't need __init__.py files everywhere. Modern Python packaging is less fussy than it used to be.

The actual code in src/learningpython/lp2/main.py is about as simple as it gets:

def greet():
    print("Hello from learning-python!")

if __name__ == "__main__":
    greet()

Nothing to it. The if __name__ == "__main__" bit means the function runs when you execute the file directly, but not when you import it as a module. Standard Python pattern.

With all this in place, I could build and run the container:

$ docker compose -f docker/docker-compose.yml up --detach
[+] Running 2/2
 ✔ Volume "learning-python_venv"  Created
 ✔ Container learning-python-python-1  Started

$ docker exec learning-python-python-1 uv run howdy
Hello from learning-python!

Right. Basic container works, simple function prints output. Time to sort out testing.

Installing pytest and development dependencies

Python separates runtime dependencies from development dependencies. Runtime deps go in the dependencies array, dev deps go in [dependency-groups]. Things like test frameworks and linters are dev dependencies - you need them for development but not for running the actual application.

To add pytest, I used uv add --dev pytest. This is the Python equivalent of composer require --dev in PHP or npm install --save-dev in Node. The --dev flag tells uv to put it in the dev dependency group rather than treating it as a runtime requirement.

I wanted to pin pytest to major version 8, so I checked PyPI (pypi.org/project/pytest/) to see what was current. As of writing it's 8.4.2. Python uses different version constraint syntax than Composer - instead of ^8.0 you write >=8.0,<9.0. More verbose but explicit.

I also wanted a file watcher like vitest has. There's pytest-watch but it hasn't been maintained since 2020 and doesn't work with modern pyproject.toml files. There's a newer alternative called pytest-watcher that handles the modern Python tooling properly.

After running uv add --dev pytest pytest-watcher, the pyproject.toml updated to include:

[dependency-groups]
dev = [
    "pytest>=8.4.2,<9",
    "pytest-watcher>=0.4.3,<0.5",
]

The uv.lock file pins the exact versions that were installed, giving reproducible builds. It's the Python equivalent of composer.lock or package-lock.json.

Writing the first test

pytest discovers test files automatically. It looks for files named test_*.py or *_test.py and runs functions in them that start with test_. No configuration needed for basic usage.

I created tests/lp2/test_main.py to test the greet() function. The test needed to verify that calling greet() outputs the expected message to stdout. pytest has a built-in fixture called capsys that captures output streams:

from learningpython.lp2.main import greet

def test_greet(capsys):
    greet()
    captured = capsys.readouterr()
    assert captured.out == "Hello from learning-python!\n"

The capsys parameter is a pytest fixture - you just add it as a function parameter and pytest provides it automatically. Calling readouterr() gives you back stdout and stderr as a named tuple. The \n at the end is because Python's print() adds a newline by default.

Running the test:

$ docker exec learning-python-python-1 uv run pytest
======================================= test session starts ========================================
platform linux -- Python 3.11.13, pytest-8.4.2, pluggy-1.6.0
rootdir: /usr/src/app
configfile: pyproject.toml
collected 1 item

tests/lp2/test_main.py .                                                                     [100%]

======================================== 1 passed in 0.01s =========================================

Green. The test found the pyproject.toml config automatically and discovered the test file without needing to tell it where to look.

For continuous testing, pytest-watcher monitors files and re-runs tests on changes:

$ docker exec learning-python-python-1 uv run ptw
[ptw] Watching directories: ['src', 'tests']
[ptw] Running: pytest
======================================= test session starts ========================================
platform linux -- Python 3.11.13, pytest-8.4.2, pluggy-1.6.0
rootdir: /usr/src/app
configfile: pyproject.toml
collected 1 item

tests/lp2/test_main.py .                                                                     [100%]

======================================== 1 passed in 0.01s =========================================

Any time I change a file in src or tests, it automatically re-runs the relevant tests. Much faster feedback loop than running tests manually each time.

Code formatting and linting with ruff

Python has a bunch of tools for code quality - black for formatting, flake8 for linting, isort for import sorting. Or you can just use ruff, which consolidates all of that into one fast tool written in Rust.

Installation was the same pattern: uv add --dev ruff. This added "ruff>=0.8.4,<0.9" to the dev dependencies.

ruff has two main commands:

ruff check - linting (finds unused variables, style issues, code problems)
ruff format - formatting (fixes indentation, spacing, line length)

Testing it out with some deliberately broken code:

$ docker exec learning-python-python-1 uvx ruff check src/learningpython/lp2/main.py
F841 Local variable `a` is assigned to but never used
 --> src/learningpython/lp2/main.py:2:8
  |
1 | def greet():
2 |        a = "wootywoo"
  |        ^
3 |        print("Hello from learning-python!")
  |
help: Remove assignment to unused variable `a`

It caught the unused variable. It also didn't complain about the 7-space indentation, because ruff check is about code issues, not formatting. That's what ruff format is for:

$ docker exec learning-python-python-1 uvx ruff format src/learningpython/lp2/main.py
1 file reformatted

This fixed the indentation to Python's standard 4 spaces. The check command can also auto-fix some issues with --fix, similar to eslint.

I configured IntelliJ to run ruff format on save. Had to disable a conflicting AMD Adrenaline hotkey first - video driver software stealing IDE shortcuts is always fun to debug. It took about an hour to work out WTF was going on there. I really don't understand why AMD thinks its driver software needs hotkeys. Dorks.

A Python gotcha: hyphens in paths

I reorganised the code by ticket number, so I moved the erstwhile main.py to src/learningpython/lp-2/main.py. Updated the pyproject.toml entry point to match:

[project.scripts]
howdy = "learningpython.lp-2.main:greet"

This did not go well:

$ docker exec learning-python-python-1 uv run howdy
      Built learning-python @ file:///usr/src/app
Uninstalled 1 package in 0.37ms
Installed 1 package in 1ms
  File "/usr/src/app/.venv/bin/howdy", line 4
    from learningpython.lp-2.main import greet
                            ^
SyntaxError: invalid decimal literal

Python's import system doesn't support hyphens in module names. When it sees lp-2, it tries to parse it as "lp minus 2" and chokes. Module names need to be valid Python identifiers, which means letters, numbers, and underscores only.

Renaming to lp2 fixed it. No hyphens in directory names if those directories are part of the import path. You can use hyphens in filenames that you access directly (like python path/to/some-script.py), but not in anything you're importing as a module.

This caught me out because hyphens are fine in most other ecosystems. Coming from PHP and JavaScript where some-module-name is perfectly normal, Python's stricter rules take some adjustment.

Wrapping up

So that's the development environment sorted. Docker container running Python 3.11 with uv for dependency management. pytest for testing with pytest-watcher for continuous test runs. ruff handling both linting and formatting. All the basics for writing Python code without things being annoying.

The final project structure looks like this:

learning-python/
├── docker/
│   ├── docker-compose.yml
│   └── python/
│       └── Dockerfile
├── src/
│   └── learningpython/
│       └── lp2/
│           └── main.py
├── tests/
│   └── lp2/
│       └── test_main.py
├── pyproject.toml
└── uv.lock

Everything's on GitHub at github.com/adamcameron/learning-python (tag 3.0.2).

Now I can actually start learning Python instead of fighting with tooling. Which is the point.

Righto.

--
Adam

Violating Blogger's community guidelines. Apparently.

2025-10-04T20:46:00.004+00:00

G'day:

Earlier this evening I published TypeScript decorators: not actually decorators. And about 5min after it went live, it vanished. Weird. Looking in the back-end of Blogger, I see this warning:

This post was unpublished because it violates Blogger's community guidelines. To republish, please update the content to adhere to the guidelines.

What? Seriously?

Looking through my junk folder in my email client, I had an email thus:

Hello,

As you may know, our Community Guidelines (https://blogger.com/go/contentpolicy) describe the boundaries for what we allow – and don't allow – on Blogger. Your post titled 'TypeScript decorators: not actually decorators' was flagged to us for review. We have determined that it violates our guidelines and have unpublished the URL https://blog.adamcameron.me/2025/10/typescript-decorators-not-actually.html, making it unavailable to blog readers.

If you are interested in republishing the post, please update the content to adhere to Blogger's Community Guidelines. Once the content has been updated, you may republish it at [URL removed]. This will trigger a review of the post.

You may have the option to pursue your claims in court. If you have legal questions or wish to examine legal options that may be available to you, you may want to consult your own legal counsel.

For more information, please review the following resources:

Terms of Service: https://www.blogger.com/go/terms

Blogger Community Guidelines: https://blogger.com/go/contentpolicy

Sincerely,

The Blogger Team

"OK," I thought. "I'll play yer silly game", knowing full-well I had done nothing to violate any sane T&Cs / guidelines. You can review the guidance yerself: obvs there's nothing in the article that comes anywhere near close to butting up against any of those rules.

I did make a coupla edits and resubmitted it:

Updated text in the first para to read "what the heck". You can imagine what it said before the edit. Not the only instance of that word in this blog, as one can imagine.
I was using my son's name instead of "Jed Dough". I have used Z's name a lot in the past, so can't see it was that.
I used a very cliched common password as sample data in place of tough_to_guess.
I removed most of one para. The para starting "Worth learning?" went on to explain how some noted TypeScript frameworks used decorators heavily. Why did I remove this? Well: Claudia wrote it, and this came from her knowledge not my own. I didn't know those frameworks even existed, let alone used decorators. I admonished her for using original "research", but I also went through and verified that she was correct in what she was saying. To me this was harmless and useful info: but it wasn't my own work, so I thought I'd get rid. I had included a note there that it was her and not me. There's nothing in the T&Cs that said one cannot use AI to help writing these articles, but I know people are getting a bit pearl-clutchy about the whole thing ATM, so figured it might be that. Daft though, given it was an admission it was AI-written; rather than try to shadily pass AI work as my own. Which, if you read this blog, I don't do. I always say when she's helped me draft things. And I always read what she's done ands tweak where necessary anyhow. It's my work.

And that was it. But maybe 30min later I got another email from them:

Hello,

We have re-evaluated the post titled 'TypeScript decorators: not actually decorators' against our Community Guidelines (https://blogger.com/go/contentpolicy). Upon review, the post has been reinstated. You may access the post at https://blog.adamcameron.me/2025/10/typescript-decorators-not-actually.html.

Sincerely,
The Blogger Team

Cool. No harm done, but I'd really like to know what triggered it. Of course they can't tell me as that would be leaking info that bad-actors could then use to circumvent their system. I get that. And it's better to err on the side of caution in these matters I guess.

Anyway, that was a thing.

Righto.

--
Adam (who wrote every word of this one. How bloody tedious)

TypeScript decorators: not actually decorators

2025-10-04T16:36:00.010+00:00

G'day:

I've been working through TypeScript classes, and when I got to decorators I hit the @ syntax and thought "hang on, what the heck is all this doing inside the class being decorated? The class shouldn't know it's being decorated. Fundamentally it shouldn't know."

Turns out TypeScript decorators have bugger all to do with the Gang of Four decorator pattern. They're not about wrapping objects at runtime to extend behavior. They're metaprogramming annotations - more like Java's @annotations or C#'s [attributes] - that modify class declarations at design time using the @ syntax.

The terminology collision is unfortunate. Python had the same debate back in PEP 318 - people pointed out that "decorator" was already taken by a well-known design pattern, but they went with it anyway because the syntax visually "decorates" the function definition. TypeScript followed Python's lead: borrowed the @ syntax, borrowed the confusing name, and now we're stuck with it.

So this isn't about the decorator pattern at all. This is about TypeScript's metaprogramming features that happen to be called decorators for historical reasons that made sense to someone, somewhere.

What TypeScript deco

What TypeScript decorators actually do

A decorator in TypeScript is a function that takes a target (the thing being decorated - a class, method, property, whatever) and a context object, and optionally returns a replacement. They execute at class definition time, not at runtime.

The simplest example is a getter decorator:

function obscurer(
  originalMethod: (this: PassPhrase) => string,
  context: ClassGetterDecoratorContext
) {
  void context
  function replacementMethod(this: PassPhrase) {
    const duplicateOfThis: PassPhrase = Object.assign(
      Object.create(Object.getPrototypeOf(this) as PassPhrase),
      this,
      { _text: this._text.replace(/./g, '*') }
    ) as PassPhrase

    return originalMethod.call(duplicateOfThis)
  }

  return replacementMethod
}

export class PassPhrase {
  constructor(protected _text: string) {}

  get plainText(): string {
    return this._text
  }

  @obscurer
  get obscuredText(): string {
    return this._text
  }
}

(from accessor.ts)

The decorator function receives the original getter and returns a replacement that creates a modified copy of this, replaces the _text property with asterisks, then calls the original getter with that modified context. The original instance is untouched - we're not mutating state, we're intercepting the call and providing different data to work with. The @obscurer syntax applies the decorator to the getter.

The test shows this in action:

it('original text remains unchanged', () => {
  const phrase = new PassPhrase('tough_to_guess')
  expect(phrase.obscuredText).toBe('**************')
  expect(phrase.plainText).toBe('tough_to_guess')
})

(from accessor.test.ts)

The obscuredText getter returns asterisks, the plainText getter returns the original value. The decorator wraps one getter without affecting the other or mutating the underlying _text property.

Method decorators and decorator factories

Method decorators work the same way as getter decorators, except they handle methods with actual parameters. More interesting is the decorator factory pattern - a function that returns a decorator, allowing runtime configuration.

Here's an authentication service with logging:

interface Logger {
  log(message: string): void
}

const defaultLogger: Logger = console

export class AuthenticationService {
  constructor(private directoryServiceAdapter: DirectoryServiceAdapter) {}

  @logAuth()
  authenticate(userName: string, password: string): boolean {
    const result: boolean = this.directoryServiceAdapter.authenticate(
      userName,
      password
    )
    if (!result) {
      throw new AuthenticationException(
        `Authentication failed for user ${userName}`
      )
    }
    return result
  }
}

function logAuth(logger: Logger = defaultLogger) {
  return function (
    originalMethod: (
      this: AuthenticationService,
      userName: string,
      password: string
    ) => boolean,
    context: ClassMethodDecoratorContext<
      AuthenticationService,
      (userName: string, password: string) => boolean
    >
  ) {
    void context
    function replacementMethod(
      this: AuthenticationService,
      userName: string,
      password: string
    ) {
      logger.log(`Authenticating user ${userName}`)
      try {
        const result = originalMethod.call(this, userName, password)
        logger.log(`User ${userName} authenticated successfully`)
        return result
      } catch (e) {
        logger.log(`Authentication failed for user ${userName}: ${e}`)
        throw e
      }
    }
    return replacementMethod
  }
}

(from method.ts)

The factory function takes a logger parameter and returns the actual decorator function. The decorator wraps the method with logging: logs before calling, logs on success, logs on failure and re-throws. The @logAuth() syntax calls the factory which returns the decorator.

Worth noting: the logger has to be configured at module level because @logAuth() executes when the class is defined, not when instances are created. This means tests can't easily inject different loggers per instance - you're stuck with whatever was configured when the file loaded. It's a limitation of how decorators work, and honestly it's a bit crap for dependency injection.

Also note I'm just using the console as the logger here. It makes testing easy.

Class decorators and shared state

Class decorators can replace the entire class, including hijacking the constructor. This example is thoroughly contrived but demonstrates how decorators can inject stateful behavior that persists across all instances:

const maoriNumbers = ['tahi', 'rua', 'toru', 'wha']
let current = 0
function* generator() {
  while (current < maoriNumbers.length) {
    yield maoriNumbers[current++]
  }
  throw new Error('No more Maori numbers')
}

function maoriSequence(
  target: typeof Number,
  context: ClassDecoratorContext
) {
  void context

  return class extends target {
    _value = generator().next().value as string
  }
}

type NullableString = string | null

@maoriSequence
export class Number {
  constructor(protected _value: NullableString = null) {}

  get value(): NullableString {
    return this._value
  }
}

(from class.ts)

The class decorator returns a new class that extends the original, overriding the _value property with the next value from a generator. The generator and its state live at module scope, so they're shared across all instances of the class. Each time you create a new instance, the constructor parameter gets completely ignored and the decorator forces the next Maori number instead:

it('intercepts the constructor', () => {
  expect(new Number().value).toEqual('tahi')
  expect(new Number().value).toEqual('rua')
  expect(new Number().value).toEqual('toru')
  expect(new Number().value).toEqual('wha')
  expect(() => new Number()).toThrowError('No more Maori numbers')
})

(from class.test.ts)

First instance gets 'tahi', second gets 'rua', third gets 'toru', fourth gets 'wha', and the fifth throws an error because the generator is exhausted. The state persists across all instantiations because it's in the decorator's closure at module level.

This demonstrates that class decorators can completely hijack construction and maintain shared state, which is both powerful and horrifying. You'd never actually do this in real code - it's terrible for testing, debugging, and reasoning about behavior - but it shows the level of control decorators have over class behavior.

GitHub Copilot's code review was appropriately horrified by this. It flagged the module-level state, the generator that never resets, the constructor hijacking, and basically everything else about this approach. Fair cop - the code reviewer was absolutely right to be suspicious. This is demonstration code showing what's possible with decorators, not what you should actually do. In real code, if you find yourself maintaining stateful generators at module scope that exhaust after four calls and hijack constructors to ignore their parameters, you've gone badly wrong somewhere and need to step back and reconsider your life choices.

Auto-accessors and the `accessor` keyword

Auto-accessors are a newer feature that provides shorthand for creating getter/setter pairs with a private backing field. The accessor keyword does automatically what you'd normally write manually:

export class Person {
  @logCalls(defaultLogger)
  accessor firstName: string

  @logCalls(defaultLogger)
  accessor lastName: string

  constructor(firstName: string, lastName: string) {
    this.firstName = firstName
    this.lastName = lastName
  }

  getFullName(): string {
    return `${this.firstName} ${this.lastName}`
  }
}

(from autoAccessors.ts)

The accessor keyword creates a private backing field plus public getter and setter, similar to C# auto-properties. The decorator can then wrap both operations:

function logCalls(logger: Logger = defaultLogger) {
  return function (
    target: ClassAccessorDecoratorTarget,
    context: ClassAccessorDecoratorContext
  ) {
    const result: ClassAccessorDecoratorResult = {
      get(this: This) {
        logger.log(`[${String(context.name)}] getter called`)
        return target.get.call(this)
      },
      set(this: This, value) {
        logger.log(
          `[${String(context.name)}] setter called with value [${String(value)}]`
        )
        target.set.call(this, value)
      }
    }

    return result
  }
}

(from autoAccessors.ts)

The target provides access to the original get and set methods, and the decorator returns a result object with replacement implementations. The getter wraps the original with logging before calling it, and the setter does the same.

Testing shows both operations getting logged:

it('should log the setters being called', () => {
  const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
  new Person('Jed', 'Dough')

  expect(consoleSpy).toHaveBeenCalledWith(
    '[firstName] setter called with value [Jed]'
  )
  expect(consoleSpy).toHaveBeenCalledWith(
    '[lastName] setter called with value [Dough]'
  )
})

it('should log the getters being called', () => {
  const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
  const person = new Person('Jed', 'Dough')

  expect(person.getFullName()).toBe('Jed Dough')
  expect(consoleSpy).toHaveBeenCalledWith('[firstName] getter called')
  expect(consoleSpy).toHaveBeenCalledWith('[lastName] getter called')
})

(from autoAccessors.test.ts)

The constructor assignments trigger the setters, which get logged. Later when getFullName() accesses the properties, the getters are logged.

Auto-accessors are actually quite practical compared to the other decorator types. They provide a clean way to add cross-cutting concerns like logging, validation, or change tracking to properties without cluttering the class with boilerplate getter/setter implementations.

What I learned

TypeScript decorators are metaprogramming tools that modify class behavior at design time. They're useful for cross-cutting concerns like logging, validation, or instrumentation - the kinds of things that would otherwise clutter your actual business logic.

The main decorator types are:

Getter/setter decorators - wrap property access
Method decorators - wrap method calls
Class decorators - replace or modify entire classes
Auto-accessor decorators - wrap the getter/setter pairs created by the accessor keyword

Decorator factories (functions that return decorators) allow runtime configuration, though "runtime" here means "when the module loads", not "when instances are created". This makes dependency injection awkward - you're stuck with module-level state or global configuration.

The syntax is straightforward once you understand the pattern: decorator receives target and context, returns replacement (or modifies via context), job done. The tricky bit is the type signatures and making sure your implementation signature is flexible enough to handle all the overloads you're declaring.

But fundamentally, these aren't decorators in the design pattern sense. They're annotations that modify declarations. If you're coming from a language with proper decorators (the GoF pattern), you'll need to context-switch your brain because the @ syntax is doing something completely different here.

Worth learning? Yeah, if only because you'll see them in the wild and need to understand what they're doing.

Would I use them in my own code? Probably sparingly. Auto-accessors are legitimately useful. Method decorators for logging or metrics could work if you're comfortable with the module-level configuration limitations. Class decorators that hijack constructors and maintain shared state can absolutely get in the sea.

But to be frank: if I wanted to decorate something - in the accurate sense of that term - I'd do it properly using the design pattern, and DI.

The full code for this investigation is in my learning-typescript repository.

Righto.

--
Adam

TypeScript mixins: poor person's composition, but with generics

2025-10-02T08:28:00.002+00:00

G'day:

I've been working through TypeScript classes, and today I hit mixins. For those unfamiliar, mixins are a pattern for composing behavior from multiple sources - think Ruby's modules or PHP's traits. They're basically "poor person's composition" - a way to share behavior between classes when you can't (or won't) use proper dependency injection.

I think they're a terrible pattern. If I need shared behavior, I'd use actual composition - create a proper class and inject it as a dependency. But I'm not always working with my own code, and mixins do exist in the wild, so here we are.

The TypeScript mixin implementation is interesting though - it's built on generics and functions that return classes, which is quite different from the prototype-mutation approach you see in JavaScript. And despite my reservations about the pattern itself, understanding how it works turned out to be useful for understanding TypeScript's type system better.

The basic pattern

TypeScript mixins aren't about mutating prototypes at runtime (though you can do that in JavaScript). They're functions that take a class and return a new class that extends it.

For this example, I wanted a mixin that would add a flatten() method to any class - something that takes all the object's properties and concatenates their values into a single string. Not particularly useful in real code, but simple enough to demonstrate the mechanics without getting lost in business logic.

type Constructor = new (...args: any[]) => {}

function applyFlattening<TBase extends Constructor>(Base: TBase) {
  return class Flattener extends Base {
    flatten(): string {
      return Object.entries(this).reduce(
        (flattened: string, [_, value]): string => {
          return flattened + String(value)
        },
        ''
      )
    }
  }
}

(from mixins.ts)

That Constructor type is saying "anything that can be called with new and returns an object". The mixin function takes a class that matches this type and returns a new anonymous class that extends the base class with additional behavior.

You can then apply it to any class:

export class Name {
  constructor(
    public firstName: string,
    public lastName: string
  ) {}

  get fullName(): string {
    return `${this.firstName} ${this.lastName}`
  }
}

export const FlattenableName = applyFlattening(Name)

FlattenableName is now a class that has everything Name had plus the flatten() method. TypeScript tracks all of this at compile time, so you get proper type checking and autocomplete for both the base class members and the mixin methods.

The generics bit

The confusing part (at least initially) is this bit:

function applyFlattening<TBase extends Constructor>(Base: TBase)

Without understanding generics, this is completely opaque. The <TBase extends Constructor> is saying "this function is generic over some type TBase, which must be a constructor". The Base: TBase parameter then uses that type.

This lets TypeScript track what specific class you're mixing into. When you call applyFlattening(Name), TypeScript knows that TBase is specifically the Name class, so it can infer that the returned class has both Name's properties and methods plus the flatten() method.

Without generics, TypeScript would only know "some constructor was passed in" and couldn't give you proper type information about what the resulting class actually contains. The generic parameter preserves the type information through the composition.

I hadn't covered generics properly before hitting this (it's still on my todo list), which made the mixin syntax particularly cryptic. But the core concept is straightforward once you understand that generics are about preserving type information as you transform data - in this case, transforming a class into an extended version of itself.

Using the mixed class

Once you've got the mixed class, using it is straightforward:

const flattenableName: InstanceType<typeof FlattenableName> =
  new FlattenableName('Zachary', 'Lynch')
expect(flattenableName.fullName).toEqual('Zachary Lynch')

const flattenedName: string = flattenableName.flatten()
expect(flattenedName).toEqual('ZacharyLynch')

(from mixins.test.ts)

The InstanceType<typeof FlattenableName> bit is necessary because FlattenableName is a value (the constructor function), not a type. typeof FlattenableName gives you the constructor type, and InstanceType<...> extracts the type of instances that constructor creates.

Once you've got an instance, it has both the original Name functionality (the fullName getter) and the new flatten() method. The mixin has full access to this, so it can see all the object's properties - in this case, firstName and lastName.

Constraining the mixin

The basic Constructor type accepts any class - it doesn't care what properties or methods the class has. But you can constrain mixins to only work with classes that have specific properties:

type NameConstructor = new (
  ...args: any[]
) => {
  firstName: string
  lastName: string
}

function applyNameFlattening<TBase extends NameConstructor>(Base: TBase) {
  return class NameFlattener extends Base {
    flatten(): string {
      return this.firstName + this.lastName
    }
  }
}

(from mixins.ts)

The NameConstructor type specifies that the resulting instance must have firstName and lastName properties. Now the mixin can safely access those properties directly - TypeScript knows they'll exist.

You can't constrain the constructor parameters themselves - that ...args: any[] is mandatory for mixin functions. TypeScript requires this because the mixin doesn't know what arguments the base class constructor needs. You can only constrain the instance type (the return type of the constructor).

This means a class like this won't work with the constrained mixin:

export class ShortName {
  constructor(public firstName: string) {}
}
// This won't compile:
// export const FlattenableShortName = applyNameFlattening(ShortName)
// Argument of type 'typeof ShortName' is not assignable to parameter of type 'NameConstructor'

TypeScript correctly rejects it because ShortName doesn't have a lastName property, and the mixin's flatten() method needs it.

Chaining multiple mixins

You can apply multiple mixins by chaining them - pass the result of one mixin into another:

function applyArrayifier<TBase extends Constructor>(Base: TBase) {
  return class Arrayifier extends Base {
    arrayify(): string[] {
      return Object.entries(this).reduce(
        (arrayified: string[], [_, value]): string[] => {
          return arrayified.concat(String(value).split(''))
        },
        []
      )
    }
  }
}

export const ArrayableFlattenableName = applyArrayifier(FlattenableName)

(from mixins.ts)

Now ArrayableFlattenableName has everything from Name, plus flatten() from the first mixin, plus arrayify() from the second mixin:

const transformableName: InstanceType<typeof ArrayableFlattenableName> =
  new ArrayableFlattenableName('Zachary', 'Lynch')
expect(transformableName.fullName).toEqual('Zachary Lynch')

const flattenedName: string = transformableName.flatten()
expect(flattenedName).toEqual('ZacharyLynch')

const arrayifiedName: string[] = transformableName.arrayify()
expect(arrayifiedName).toEqual('ZacharyLynch'.split(''))

(from mixins.test.ts)

TypeScript correctly infers that all three sets of functionality are available on the final class. The type information flows through each composition step.

Why not just use composition?

Right, so having learned how mixins work in TypeScript, I still think they're a poor choice for most situations. If you need shared behavior, use actual composition:

class Flattener {
  flatten(obj: Record<string, unknown>): string {
    return Object.entries(obj).reduce(
      (flattened, [_, value]) => flattened + String(value),
      ''
    )
  }
}

class Name {
  constructor(
    public firstName: string,
    public lastName: string,
    private flattener: Flattener
  ) {}
  
  flatten(): string {
    return this.flattener.flatten(this)
  }
}

This is clearer about dependencies, easier to test (inject a mock Flattener), and doesn't require understanding generics or the mixin pattern. The behavior is in a separate class that can be reused anywhere, not just through inheritance chains.

Mixins make sense in languages where you genuinely can't do proper composition easily, or where the inheritance model is the primary abstraction. But TypeScript has first-class support for dependency injection and composition. Use it.

The main legitimate use case I can see for TypeScript mixins is when you're working with existing code that uses them, or when you need to add behavior to classes you don't control. Otherwise, favor composition.

The abstract class limitation

One thing you can't do with mixins is apply them to abstract classes. The pattern requires using new Base(...) to instantiate and extend the base class, but abstract classes can't be instantiated - that's their whole point.

abstract class AbstractBase {
  abstract doSomething(): void
}

// This won't work:
// const Mixed = applyMixin(AbstractBase)
// Cannot create an instance of an abstract class

The workarounds involve either making the base class concrete (which defeats the purpose of having it abstract), or mixing into a concrete subclass instead of the abstract parent. Neither is particularly satisfying.

This is a fundamental incompatibility between "can't instantiate" (abstract classes) and "must instantiate to extend" (the mixin pattern). It's another reason to prefer composition - you can absolutely inject abstract dependencies through constructor parameters without these limitations.

What I learned

TypeScript mixins are functions that take classes and return extended classes. They use generics to preserve type information through the composition, and TypeScript tracks everything at compile time so you get proper type checking.

The syntax is more complicated than it needs to be (that type Constructor = new (...args: any[]) => {} bit), and you need to understand generics before any of it makes sense. The InstanceType<typeof ClassName> dance is necessary because of how TypeScript distinguishes between constructor types and instance types.

You can constrain mixins to only work with classes that have specific properties, and you can chain multiple mixins together. But you can't use them with abstract classes, and they're generally a worse choice than proper composition for most real-world scenarios.

I learned the pattern because I'll encounter it in other people's code, not because I plan to use it myself. If I need shared behavior, I'll use dependency injection and composition like a sensible person. But now at least I understand what's happening when I see const MixedClass = applyMixin(BaseClass) in a codebase.

The full code for this investigation is in my learning-typescript repository. Thanks to Claudia for helping work through the type constraints and the abstract class limitation, and for assistance with this write-up.

Righto.

--
Adam

TypeScript constructor overloading: when one implementation has to handle multiple signatures

2025-09-30T20:57:00.002+00:00

G'day:

I've been working through TypeScript classes, and today I hit constructor overloading. Coming from PHP where you can't overload constructors at all (you get one constructor, that's it), the TypeScript approach seemed straightforward enough: declare multiple signatures, implement once, job done.

Turns out the "implement once" bit is where things get interesting.

The basic pattern

TypeScript lets you declare multiple constructor signatures followed by a single implementation:

constructor()
constructor(s: string)
constructor(n: number)
constructor(s: string, n: number)
constructor(p1?: string | number, p2?: number) {
  // implementation handles all four cases
}

The first four lines are just declarations - they tell TypeScript "these are the valid ways to call this constructor". The final signature is the actual implementation that has to handle all of them.

Simple enough when you've got a no-arg constructor and a two-arg constructor - those are clearly different. But what happens when you need two different single-argument constructors, one taking a string and one taking a number?

That's where I got stuck.

The implementation signature problem

Here's what I wanted to support:

const empty = new Numeric()                    // both properties null
const justString = new Numeric('forty-two')    // asString set, asNumeric null
const justNumber = new Numeric(42)             // asNumeric set, asString null
const both = new Numeric('forty-two', 42)      // both properties set

(from constructors.test.ts)

My first attempt at the implementation looked like this:

constructor()
constructor(s: string)
constructor(s: string, n: number)
constructor(s?: string, n?: number) {
  this.asString = s ?? null
  this.asNumeric = n ?? null
}

Works fine for the no-arg, single-string, and two-arg cases. But then I needed to add the single-number constructor:

constructor(n: number)

And suddenly the compiler wasn't happy: "This overload signature is not compatible with its implementation signature."

The error pointed at the new overload, but the actual problem was in the implementation. It took me ages (and asking Claudia) to work this out. This is entirely down to me not reading, but just looking at what line it was pointing too. Duh. The first parameter was typed as string (or undefined), but the new overload promised it could also be a number. The implementation couldn't deliver on what the overload signature was promising.

Why neutral parameter names matter

The fix was to change the implementation signature to accept both types:

constructor(p1?: string | number, p2?: number) {
  // ...
}

But here's where the parameter naming became important. My initial instinct was to keep using meaningful names like s and n:

constructor(s?: string | number, n?: number)

This felt wrong. When you're reading the implementation code and you see a parameter called s, you expect it to be a string. But now it might be a number. The name actively misleads you about what the parameter contains.

Switching to neutral names like p1 and p2 made the implementation logic much clearer - these are just "parameter slots" that could contain different types depending on which overload was called. No assumptions about what they contain.

Runtime type checking

Once the implementation signature accepts both types, you need runtime logic to figure out which overload was actually called:

constructor(p1?: string | number, p2?: number) {
  if (typeof p1 === 'number' && p2 === undefined) {
    this.asNumeric = p1
    return
  }
  this.asString = (p1 as string) ?? null
  this.asNumeric = p2 ?? null
}

(from constructors.ts)

The first check handles the single-number case: if the first parameter is a number and there's no second parameter, we're dealing with new Numeric(42). Set asNumeric and bail out.

Everything else falls through to the default logic: treat the first parameter as a string (or absent) and the second parameter as a number (or absent). This covers the no-arg, single-string, and two-arg cases.

The type assertion (p1 as string) is necessary because TypeScript can't prove that p1 is a string at that point - we've only eliminated the case where it's definitely a number. From the compiler's perspective, it could still be string | number | undefined.

The bug I didn't notice

I had the implementation working and all my tests passing. Job done, right? Except when I submitted the PR, GitHub Copilot's review flagged this:

this.asString = (p1 as string) || null
this.asNumeric = p2 || null

The logic for handling empty strings is incorrect. An empty string ('') will be converted to null due to the || operator, but empty strings should be preserved as valid string values. Use nullish coalescing (??) instead or explicit null checks.

Copilot was absolutely right. The || operator treats all falsy values as "use the right-hand side", which includes:

'' (empty string)
0 (zero)
false
null
undefined
NaN

So new Numeric('') would set asString to null instead of '', and new Numeric('test', 0) would set asNumeric to null instead of 0. Both are perfectly valid values that the constructor should accept.

The ?? (nullish coalescing) operator only treats null and undefined as "use the right-hand side", which is exactly what I needed:

this.asString = (p1 as string) ?? null
this.asNumeric = p2 ?? null

Now empty strings and zeros are preserved as valid values.

Testing the edge cases

The fact that this bug existed meant my initial tests weren't comprehensive enough. I'd tested the basic cases but missed the edge cases where valid values happen to be falsy.

I added tests for empty strings and zeros:

it('accepts an empty string as the only argument', () => {
  const o: Numeric = new Numeric('')

  expect(o.asString).toEqual('')
  expect(o.asNumeric).toBeNull()
})

it('accepts zero as the only argument', () => {
  const o: Numeric = new Numeric(0)

  expect(o.asNumeric).toEqual(0)
  expect(o.asString).toBeNull()
})

it('accepts an empty string as the first argument', () => {
  const o: Numeric = new Numeric('', -1)

  expect(o.asString).toEqual('')
})

it('accepts zero as the second argument', () => {
  const o: Numeric = new Numeric('NOT_TESTED', 0)

  expect(o.asNumeric).toEqual(0)
})

(from constructors.test.ts)

With the original || implementation, all four of these tests failed. After switching to ??, they all passed. That's how testing is supposed to work - the tests catch the bug, you fix it, the tests confirm the fix.

Fair play to Copilot for spotting this in the PR review. It's easy to miss falsy edge cases when you're focused on getting the type signatures right.

Method overloading in general

Worth noting that constructor overloading is just a specific case of method overloading. Any method can use this same pattern of multiple signatures with one implementation:

class Example {
  doThing(): void
  doThing(s: string): void
  doThing(n: number): void
  doThing(p?: string | number): void {
    // implementation handles all cases
  }
}

The same principles apply: the implementation signature needs to be flexible enough to handle all the declared overloads, and you need runtime type checking to figure out which overload was actually called.

Constructors just happen to be where I first encountered this pattern, because that's where you often want multiple ways to initialize an object with different combinations of parameters.

What I learned

Constructor overloading in TypeScript is straightforward once you understand that the implementation signature has to be a superset of all the overload signatures. The tricky bit is when you have overloads that look similar but take different types - that's when you need union types and runtime type checking to make it work.

Using neutral parameter names in the implementation helps avoid confusion about what types you're actually dealing with. And edge case testing matters - falsy values like empty strings and zeros are valid inputs that need explicit test coverage.

The full code is in my learning-typescript repository if you want to see the complete implementation. Thanks to Claudia for helping me understand why that compilation error was pointing at the overload when the problem was in the implementation, and to GitHub Copilot for catching the || vs ?? bug in the PR review.

Righto.

--
Adam

TypeScript late static binding: parameters that aren't actually parameters

2025-09-29T20:36:00.005+00:00

G'day:

I've been working through classes in TypeScript as part of my learning project, and today I hit static methods. Coming from PHP, one of the first questions that popped into my head was "how does late static binding work here?"

In PHP, you can do this:

class Base {
    static function create() {
        return new static();  // Creates instance of the actual called class
    }
}

class Child extends Base {}

$instance = Child::create();  // Returns a Child instance, not Base

The static keyword in new static() means "whatever class this method was actually called on", not "the class where this method is defined". It's late binding - the class is resolved at runtime based on how the method was called.

Seemed like a reasonable thing to want in TypeScript. Turns out it's possible, but the syntax is... questionable.

The TypeScript approach

Here's what I ended up with:

export class TranslatedNumber {
  constructor(
    private value: number,
    private en: string,
    private mi: string
  ) {}

  getAll(): { value: number; en: string; mi: string } {
    return {
      value: this.value,
      en: this.en,
      mi: this.mi,
    }
  }

  static fromTuple<T extends typeof TranslatedNumber>(
    this: T,
    values: [value: number, en: string, mi: string]
  ): InstanceType<T> {
    return new this(...values) as InstanceType<T>
  }
}

export class ShoutyTranslatedNumber extends TranslatedNumber {
  constructor(value: number, en: string, mi: string) {
    super(value, en.toUpperCase(), mi.toUpperCase())
  }
}

(from static.ts)

And it works - when you call ShoutyTranslatedNumber.fromTuple(), you get a ShoutyTranslatedNumber instance back, not a TranslatedNumber:

const translated = ShoutyTranslatedNumber.fromTuple([3, 'three', 'toru'])

expect(translated.getAll()).toEqual({
  value: 3,
  en: 'THREE',
  mi: 'TORU',
})

(from static.test.ts)

The late binding works. But look at that fromTuple method signature again. Specifically this bit: this: T.

Parameters that aren't parameters

When I first saw this: T in the parameter list, my immediate reaction was "okay, so I need to pass the class as the first argument?"

But the usage doesn't have any extra parameter:

const translated = ShoutyTranslatedNumber.fromTuple([3, 'three', 'toru'])

No class being passed. Just the tuple. So what the hell is this: T, doing in the parameter list?

Turns out it's a TypeScript-specific construct that exists purely for the type system. It's not a runtime parameter at all - it gets completely erased during compilation. It's a type hint that tells TypeScript "remember which class this static method was called on".

When you write ShoutyTranslatedNumber.fromTuple([3, 'three', 'toru']), TypeScript infers:

The this inside fromTuple refers to ShoutyTranslatedNumber
Therefore T is typeof ShoutyTranslatedNumber
Therefore InstanceType<T> is ShoutyTranslatedNumber

It's clever. It works. But it's also completely bizarre if you're coming from any language where parameters are just parameters.

Why this feels wrong

The thing that bothers me about this isn't that it doesn't work - it does work fine. It's that the solution is a hack at the type system level when it should be a language feature.

TypeScript could have introduced syntax like new static() or new this() and compiled it to whatever JavaScript pattern makes it work at runtime. Instead, they've made developers express "the class this method was called on" through a phantom parameter that only exists for the type checker.

Compare this to how other languages handle it:

PHP just gives you static as a keyword. You write new static() and the compiler handles the rest.

Kotlin compiles to JavaScript too, but when you write Kotlin, you write actual Kotlin - proper classes, sealed classes, data classes, all the language features. The compiler figures out how to make it work in JavaScript. You don't write weird pseudo-parameters because "JavaScript doesn't have that feature".

TypeScript has positioned itself as "JavaScript with types" rather than "a language that compiles to JavaScript", which means it's constantly constrained by JavaScript's limitations instead of abstracting them away. When JavaScript doesn't have a concept, TypeScript makes you do the workaround instead of the compiler doing it.

It's functional, but it's not elegant. And it's definitely not intuitive.

Does it matter?

In practice? Not really. Once you know the pattern, it's straightforward enough to use. The this: T parameter becomes just another TypeScript idiom you memorise and move on.

But it does highlight a fundamental tension in TypeScript's design philosophy. The language is scared to be a proper language with its own features and syntax. Everything has to map cleanly back to JavaScript, even when that makes the developer experience worse.

I found this Stack Overflow answer while researching this, which explains the mechanics well enough, but doesn't really acknowledge how weird the solution is. It's all type theory without much "here's why the language works this way".

For now, I've got late static binding working in TypeScript. It required some generics gymnastics and a phantom parameter, but it does what I need. I'll probably dig deeper into generics in a future ticket - there's clearly more to understand there, and I've not worked with generics in any language before, so that'll be interesting.

The code for this is in my learning-typescript repository if you want to see the full implementation. Thanks to Claudia for helping me understand what the hell this: T was actually doing and for assistance with this write-up.

Righto.

--
Adam

JavaScript Symbols: when learning one thing teaches you fifteen others

2025-09-27T10:28:00.002+00:00

G'day:

This is one of those "I thought I was learning one thing but ended up discovering fifteen other weird JavaScript behaviors" situations that seems to happen every time I try to understand a JavaScript feature properly.

I was working through my TypeScript learning project, specifically tackling symbols (TS / JS) as part of understanding primitive types. Seemed straightforward enough - symbols are unique primitive values, used for creating "private" object properties and implementing well-known protocols. Easy, right?

Wrong. What started as "symbols are just unique identifiers" quickly turned into a masterclass in JavaScript's most bizarre type coercion behaviors, ESLint's opinions about legitimate code patterns, and why semicolons sometimes matter more than you think.

The basics (that aren't actually basic)

Symbols are primitive values that are guaranteed to be unique:

const s1 = Symbol();
const s2 = Symbol();
console.log(s1 === s2); // false - always unique

Except when they're not unique, because Symbol.for() maintains a global registry:

const s1 = Symbol.for('my-key');
const s2 = Symbol.for('my-key');
console.log(s1 === s2); // true - same symbol from registry

Fair enough. And you can't call Symbol as a constructor (unlike literally every other primitive wrapper):

const sym = new Symbol(); // TypeError: Symbol is not a constructor

This seemed like a reasonable safety feature until I tried to test it and discovered that TypeScript will happily let you write this nonsense, but ESLint immediately starts complaining about the any casting required to make it "work".

Where things get properly weird

The real fun starts when you encounter the well-known symbols - particularly Symbol.toPrimitive. This lets you control how objects get converted to primitive values, which sounds useful until you actually try to use it.

Here's a class that implements custom primitive conversion:

export class SomeClass {
  [Symbol.toPrimitive](hint: string) {
    if (hint === 'number') {
      return 42;
    }
    if (hint === 'string') {
      return 'forty-two';
    }
    return 'default';
  }
}

(from symbols.ts)

Now, which conversion do you think obj + '' would trigger? If you guessed "string", because you're concatenating with a string, you'd be wrong. It actually triggers the "default" hint because JavaScript's + operator is fundamentally broken.

The + operator with mixed types calls toPrimitive with hint "default", not "string". JavaScript has to decide whether this is addition or concatenation before converting the operands, so it plays it safe with the default hint. Only explicit string conversion like String(obj) or template literals get the string hint.

This is the kind of language design decision that makes you question whether the people who created JavaScript have ever actually used JavaScript.

ESLint vs. reality

Speaking of questionable decisions, try writing the template literal version:

expect(`${obj}`).toBe('forty-two');

ESLint immediately complains: "Invalid type of template literal expression". It sees a custom class being used in string interpolation and assumes you've made a mistake, despite this being exactly what Symbol.toPrimitive is designed for.

You end up with this choice:

Suppress the ESLint rule for legitimate symbol behavior
Use String(obj) explicitly (which actually works better anyway)
Cast to any and deal with ESLint complaining about that instead

Modern tooling is supposedly designed to help us write better code, but it turns out "better" doesn't include using JavaScript's actual primitive conversion protocols.

Symbols as "secret" properties

The privacy model for symbols is... interesting. They're hidden from normal enumeration but completely discoverable if you know where to look:

const secret1 = Symbol('secret1');
const secret2 = Symbol('secret2');

const obj = {
  publicProp: 'visible',
  [secret1]: 'hidden',
  [secret2]: 'also hidden'
};

console.log(Object.keys(obj));                    // ['publicProp']
console.log(JSON.stringify(obj));                 // {"publicProp":"visible"}
console.log(Object.getOwnPropertySymbols(obj));   // [Symbol(secret1), Symbol(secret2)]
console.log(Reflect.ownKeys(obj));                // ['publicProp', Symbol(secret1), Symbol(secret2)]

So symbols provide privacy from accidental access, but not from intentional inspection. It's like having a door that's closed but not locked - good enough to prevent accidents, useless against anyone who actually wants to get in.

Semicolons matter (sometimes)

While implementing symbol properties, I discovered this delightful parsing ambiguity:

export class SomeClass {
  private stringName: string = 'StringNameOfClass'
  [Symbol.toStringTag] = this.stringName  // Prettier goes mental
}

Without a semicolon after the first line, Prettier interprets this as:

private stringName: string = ('StringNameOfClass'[Symbol.toStringTag] = this.stringName)

Because you can totally set properties on string literals in JavaScript (even though it's completely pointless), the parser thinks you're doing property access and assignment chaining.

The semicolon makes it unambiguous, and impressively, Prettier is smart enough to recognize that this particular semicolon is semantically significant and doesn't remove it like it normally would.

Testing arrays vs. testing values

Completely unrelated to symbols, but I learned that Vitest's toBe() and toEqual() are different beasts:

expect(Object.keys(obj)).toBe(['publicProp']);     // Fails - different array objects
expect(Object.keys(obj)).toEqual(['publicProp']);  // Passes - same contents

toBe() uses reference equality (like Object.is()), so even arrays with identical contents are different objects. toEqual() does deep equality comparison. This seems obvious in hindsight, but when you're in the middle of testing symbol enumeration behavior, it's easy to forget that arrays are objects too.

The real lesson

I set out to learn about symbols and ended up with a tour of JavaScript's most questionable design decisions:

Type coercion that doesn't work the way anyone would expect
Operators that behave differently based on hints that don't correspond to actual usage
Tooling that warns against legitimate language features
Parsing ambiguities that require strategic semicolon placement
Privacy models that aren't actually private

This is exactly why "learn by doing" beats "read the documentation" every time. The docs would never tell you about the ESLint conflicts, the semicolon parsing gotcha, or the + operator's bizarre hint behavior. You only discover this stuff when you're actually writing code and things don't work the way they should.

The symbols themselves are fine - they do what they're supposed to do. It's everything else around them that's… erm… "laden with interesting design decision "opportunities".[Cough].

The full code for this investigation is available in my learning-typescript repository if you want to see the gory details. Thanks to Claudia for helping debug the type coercion weirdness and for assistance with this write-up. Also props to GitHub Copilot for pointing out that I had three functions doing the same thing - sometimes the robots are right.

Righto.

--
Adam

Adam Cameron's Dev Blog

Setting up dev/prod environments with Lovable and Supabase

The single environment problem

Lovable Cloud: the auto-provisioning disaster

Understanding the pieces

Environment variables in three different contexts

The VITE_SUPABASE_PROJECT_ID battle

The review workflow

The actual working solution

The architecture

The deployment process

Keeping branches in sync

Edge functions and secrets

JWT verification settings

Gotchas and non-obvious behaviours

Supabase CLI tool location changed

The "PRODUCTION" badge means nothing

npx is not npm install -g

Netlify build doesn't touch the database

React Router and direct navigation

Environment variable override precedence

Migration file format matters

Supabase key format evolution

What we ended up with

Lovable and its seemingly self-defeating pricing and business model

TypeScript: any, unknown, never

any - when you genuinely don't know or don't care

unknown - the safer alternative that's actually more annoying

Type guards - actually checking instead of just asserting

Error handling with unknown

So which one should you use?

never - the type that can't exist

Exhaustiveness checking

The actual lesson

Setting up a Python learning environment: Docker, pytest, and ruff

Getting Docker sorted

Project configuration and initial code

Installing pytest and development dependencies

Writing the first test

Code formatting and linting with ruff

A Python gotcha: hyphens in paths

Wrapping up

Violating Blogger's community guidelines. Apparently.

TypeScript decorators: not actually decorators

What TypeScript deco

What TypeScript decorators actually do

Method decorators and decorator factories

Class decorators and shared state

Auto-accessors and the accessor keyword

What I learned

TypeScript mixins: poor person's composition, but with generics

The basic pattern

The generics bit

Using the mixed class

Constraining the mixin

Chaining multiple mixins

Why not just use composition?

The abstract class limitation

What I learned

TypeScript constructor overloading: when one implementation has to handle multiple signatures

The basic pattern

The implementation signature problem

Why neutral parameter names matter

Runtime type checking

The bug I didn't notice

Testing the edge cases

Method overloading in general

What I learned

TypeScript late static binding: parameters that aren't actually parameters

The TypeScript approach

Parameters that aren't parameters

Why this feels wrong

Does it matter?

JavaScript Symbols: when learning one thing teaches you fifteen others

The basics (that aren't actually basic)

Where things get properly weird

ESLint vs. reality

Symbols as "secret" properties

Semicolons matter (sometimes)

Testing arrays vs. testing values

Auto-accessors and the `accessor` keyword