Except it didn't, this time. The CORS configuration was correct. It had been correct all this time. Every other endpoint on the same origin, through the same middleware, with the same credentials, worked. Only /auth/refresh failed, and only sometimes.

I went to the CORS config first anyway. Of course I did. That's what the error said.

TL;DR

An unhandled exception produced a 500 that never passed back through the middleware which attaches CORS headers, so the browser saw a header-less response and reported the only thing it could: a CORS failure. The message named the last layer to touch the response, not the layer that broke.

Underneath was a textbook time-of-check-to-time-of-use race in refresh-token rotation. Two tabs, one token, both passing the same "is this blacklisted?" check before either had written its answer.

The fix wasn't a better check. It was giving up on checking, letting a unique index arbitrate, and translating the resulting error. Three separate races in this codebase are now settled the same way.

This codebase was deliberately vibe coded, as a test of how far that approach goes without close architectural steering. This was a different kind of result from the cost one. That constraint lived outside the repository and no amount of reading code would have surfaced it. This one is four lines of source that anyone can read, and it got through anyway.

Why a 500 arrives as a CORS error

Worth understanding on its own, because it will cost you an afternoon exactly once and then never again.

CORS headers are attached by middleware. Middleware sits in a stack, each layer wrapping the next, and a response on the way out passes back through every layer that it passed through on the way in. That's how the header gets on there.

An unhandled exception does not come back out that way. It propagates up to the outermost error handler, which generates a 500 above the CORS layer, so the response the browser receives never went through the code that would have added Access-Control-Allow-Origin.

From the browser's side, a response with no CORS header is indistinguishable from a response that was refused on CORS grounds. It has no way to know the server crashed. It reports what it can see, which is a missing header, and you go and read documentation about preflight requests for forty minutes.

The general form is worth keeping:

When a browser reports a CORS failure on an endpoint whose CORS config you have not touched, read the server log before you read the CORS docs. The browser is describing the shape of the response, not the cause of it.

Worth separating two problems here, because fixing the race only fixes this particular 500. The general fix is a global exception handler that catches anything unhandled and returns a real response from inside your own middleware, so the response travels back out through the whole stack and arrives at the client with headers on it. The framework's own error handler sits above everything you install, which is why responses it generates look nothing like your others. You want the frontend reading a 500 and failing gracefully, not dying on what it thinks is a network error.

The server log said IntegrityError. Nothing to do with CORS at all.

What the refresh endpoint was doing

The auth design is short-lived access tokens with rotating refresh tokens. Each refresh consumes the token it was given and issues a new one, and the consumed token goes into a blacklist table keyed by its jti, its unique token identifier. A refresh token is therefore valid exactly once. Present it twice and the second attempt is refused.

That refusal is deliberate, and it isn't only bookkeeping. A rotating refresh token that gets replayed is one of the few signals you get that a token has been stolen, because the legitimate client and the attacker will both eventually present the same one. Rejecting reuse is the entire point of rotation.

The endpoint did the obvious thing:

if await blacklist.contains(jti):
    raise Unauthorized("token already used")

new_tokens = issue_pair(user)
await blacklist.add(jti)
return new_tokens

Read it and it looks correct. It reads correct out loud. Check whether the token has been used, and if it hasn't, use it.

Two tabs

The user has the application open in two tabs. Both hold the same refresh token, because it's persisted so a reload can recover the session. The access token expires. Both tabs notice at approximately the same moment and both call /auth/refresh.

Or it isn't two tabs at all, it's one tab and a retry, or a client that fired the refresh twice while the first request was still in flight. It doesn't matter which. What matters is two requests carrying the same jti, close enough together to overlap.

Request A checks the blacklist. Not there. Request A proceeds.

Request B checks the blacklist. Also not there, because A hasn't written its row yet. Request B proceeds.

Both issue a new token pair. Both then try to insert the same jti. The first insert lands. The second hits the unique index and Postgres refuses it, SQLAlchemy raises IntegrityError, nothing catches it, and it becomes a 500 that arrives in the browser wearing a CORS costume.

This is time-of-check-to-time-of-use, and it's one of those bugs that's completely obvious in retrospect and completely invisible in review, because the code says what you meant. The gap between the check and the write is where the whole thing lives. On a local machine with one tab, that gap is microseconds and you will never see it. Under any real concurrency, it's just a window, and windows get walked through.

You cannot fix this with a better check

The instinct is to tighten the check. Move it closer to the write, wrap it in a transaction, add a lock. Some of that helps. None of it addresses the shape of the problem.

SELECT then INSERT is two statements. Whatever you do between them, there is a moment when the first has returned and the second has not yet run, and in that moment another connection can be doing precisely the same thing. You can make the window narrower. You cannot make it not exist, because it is made of the fact that you asked a question and then acted on the answer.

You can go get a lock, and for some problems that's right. But you've now introduced a lock into your hottest auth path to defend against something the database was already going to catch for you, because the unique index on jti was there the whole time. It was doing its job perfectly. The only thing wrong was that nobody was listening to it.

Let the database decide

The fix is to stop asking and start attempting:

new_tokens = issue_pair(user)
try:
    await blacklist.add(jti)
except IntegrityError as e:
    await session.rollback()          # the transaction is already aborted
    if "ix_blacklist_jti" in str(e.orig):
        raise Unauthorized("please log in again")
    raise                             # a different constraint is a different bug
return new_tokens

The unique constraint is the arbiter. Exactly one insert can win, the database guarantees it under any amount of concurrency, and the loser gets told so. All that's left is translating a database error into an HTTP response.

The part I find satisfying is that the translation was already decided for us. A duplicate jti means this refresh token has been presented twice. The correct response to a replayed refresh token is to refuse it and make the user authenticate again. So the answer to the race and the answer to a stolen token are the same answer, and the endpoint doesn't need to know which situation it's in. It just needs to be honest that this token is no longer good.

One detail in there is deliberate and looks wasteful. The new token pair is issued before the insert is attempted, so the losing request does work it then throws away. That's fine, and the alternative is worse. Blacklisting first would mean consuming the old token before knowing whether you can successfully issue a replacement, and a failure between those two points logs the user out for no reason at all. Doing the cheap, reversible work first and letting the irreversible step be the one that can fail is the ordering you want whenever you can get it.

The 500 became a 401. The CORS error disappeared, because there was no longer an unhandled exception, and the browser started receiving a response that had passed through the whole middleware stack on its way out.

Three races, one pattern

Once the shape is visible you start seeing it. There were three of these in the codebase, and they're now all settled the same way:

Concurrent refresh rotation is arbitrated by UNIQUE (jti) on the blacklist table. IntegrityError becomes 401, log in again.

Double like or bookmark is arbitrated by a composite UNIQUE (user_id, story_id). This is the same bug in a friendlier costume. Someone double-taps a heart on a slow connection, or the client retries a request whose response got lost, and two inserts arrive for a row that should exist at most once. The application version of this guard reads "if the user has already liked it, return early," and it passes for both racers for exactly the same reason the token check did. The composite unique means the database enforces one like per user per story and the application stops pretending to. IntegrityError becomes 409, and the client, which was going to show a filled-in heart either way, carries on.

Concurrent story edits are arbitrated by an optimistic lock. The stories table carries a row_version column wired to SQLAlchemy's version_id_col, so every update includes the version it read and increments it. Two editors open the same story, both save, and the second UPDATE matches zero rows because the version moved underneath it. SQLAlchemy raises StaleDataError, which becomes a 409 with "this was edited while you were working."

This third one is the one I'd argue hardest for, because its failure mode is the quietest. Without the version column, both saves succeed. The second UPDATE writes the whole row over the top of the first, both requests return 200, both editors see a saved state, and the earlier person's paragraph is simply gone. Nothing errors. Nothing logs. There is no artifact anywhere in the system indicating that an edit was destroyed, and the only way anyone finds out is a human noticing their own work missing and not being believed. A 409 is a small inconvenience by comparison, and it's an inconvenience that arrives at the moment it can still be resolved.

Same structure three times. Don't prevent the race, define what winning means as a constraint, let the database enforce it, and translate the failure into something the client can act on.

The same experiment, a different kind of failure

I should say where this code came from, because it changes what the bug means.

I deliberately vibe coded most of this project. I wanted to test the claim that coding agents can build a full-stack app almost end to end, and more importantly to find where that approach failed when nobody was carefully steering the architecture. It's a personal project, which made it a safe place to let the experiment break things.

The first result I got from that was an operational one: an architecture that was entirely conventional and entirely correct, carrying a running cost that appeared nowhere in the source tree.

This one is different, because the defect is in the repository. It's four lines. And it still gets through everything. It type-checks. It can pass review, because there's nothing sloppy to point at. It passes the test suite, and it would pass a test suite twice the size, because the bug does not exist unless two requests overlap and nothing about a normal test run produces overlap. Sequential tests pass. Manual testing passes. Local development, one tab, one request at a time, passes forever.

Check-then-act is the shape you reach for by default, and that's the actual finding. It's how the requirement sounds when you say it out loud. "Don't allow a token to be used twice" becomes "check if it's been used, and if it has, refuse," and the translation from English into code feels lossless. Plenty of straightforward examples use that shape for the same reason, because it mirrors the requirement. It's the readable version, the version that explains itself, and it encodes a single-threaded picture of the world that stops being true the moment two people are using your application.

An agent reproduces convention faithfully, which is usually what you want and is exactly the problem here, because the convention is wrong. There's no sloppiness to catch. It's a correct-looking implementation of a subtly wrong idea about how time works.

A strong reviewer can catch this, and some would have. But ordinary review reads for what the code says, and catching this one requires reading for what two copies of it would do at the same moment, which is a different and more deliberate act. A concurrency test would have made it deterministic instead of leaving it to whether the reviewer happened to be in that mode that day.

What this costs you

Not free, and it's worth naming the price rather than presenting this as a pure win.

Your error translation layer becomes load-bearing. Before, an IntegrityError was an accident. Now it's part of the control flow, which means an uncaught one is a 500 you have chosen to have. Every constraint you rely on needs a handler, and the handler needs to be on the path the error actually takes.

You have to manage the transaction state. When Postgres raises an IntegrityError it aborts the current transaction. Catch it, return a response, and that connection goes back to the pool still in an aborted state, at which point the next request to pick it up dies immediately with PendingRollbackError. The failure lands on a completely unrelated request, which makes it thoroughly unpleasant to track down. Roll back explicitly in the handler.

You have to know which constraint fired. Catching IntegrityError broadly and returning 401 is fine when the table has one unique index. When a table has several, a bare except IntegrityError will happily translate a completely unrelated violation into "please log in again," which is a worse bug than the one you fixed because it's misleading. Match on the constraint name.

The error path needs the same care as the happy path. Which it always did. The difference is that now it's obvious.

And it reads as less safe than it is. A try/except around a write looks like error handling bolted on. The check looked like a real guard. The intuition is backwards, and if you're working in a team, this is a code-review conversation you'll have more than once.

What I got wrong

I spent the first stretch of this in the wrong layer entirely, reading about preflight requests and credentialed origins, because the error message told me to and I believed it. The server log had the answer in it the whole time. I hadn't looked, because the browser had already told me what was wrong with such apparent confidence.

The second thing, and it's the one I'd actually change about how I work: I knew what TOCTOU was. I could have defined it. That didn't help even slightly, because knowing the name of a bug class and recognising it in code you wrote yesterday are unrelated skills. What made it visible was not knowledge, it was reading the traceback and asking why a unique constraint could possibly be violated on a table where the application had just verified the row was absent. That question only has one answer.

Start smaller than this

If this is new, you don't need to go and audit everything. One question is enough, and you can ask it about a single endpoint:

Between the moment this code checks a condition and the moment it acts on it, could another request have changed the answer?

If it could, find out what already guarantees correctness underneath. Usually something does, and usually it's a constraint that's been sitting in your schema since the first migration, quietly doing its job while the application asks it questions it already knows the answer to.

You don't have to restructure anything today. Knowing which of your guards are real and which are polite suggestions is most of the value.

What carries over

1. A CORS error on an endpoint whose CORS config you haven't touched is probably not a CORS error. Read the server log first.
2. Middleware attaches response headers on the way out, and an unhandled exception doesn't take that route. Every error handler you rely on lives at a specific place in the stack, and errors that escape it produce responses that look nothing like your others.
3. SELECT then INSERT is two statements, and the gap between them is real. You can narrow it. You cannot close it.
4. A unique constraint is a decision, not a safety net. If the database already guarantees the thing you're checking, the check is duplicated logic that's wrong more often than the constraint is.
5. Attempt, catch, translate. Let the write fail and turn the failure into an HTTP status the client can act on.
6. Match on constraint names when a table has more than one. A broad except IntegrityError will confidently return the wrong error.
7. Check-then-act passes every test that doesn't have concurrency in it, which is most tests, which is why this survives review and reaches production.

The database was going to enforce it either way. The only question was whether the application found out politely, or as a 500 dressed up as somebody else's problem.

I'm Ashish Kr Jha, a software engineer. I build things in production and then have to live with them, which is the part that actually teaches you something. More at ashishkrjha.dev.

Neither. Sitting at the top of the list, by a comfortable margin, was a service that had spent the month doing almost nothing at all.

That service was the background worker, a Celery consumer. Its job is to pick up background tasks: moderate a story when it's published, send a verification email at signup, deliver a webhook, escalate a support ticket. On a personal project with a handful of users, that queue is empty essentially all of the time.

Every other component scaled to zero and cost nothing while idle. This one had been quietly billing me around the clock to sit and wait for work that mostly never arrived. It's a side project, so the bill is mine. I do a regular pass over billing, traffic and error rates for exactly that reason, and this was the week the billing half of it earned its keep.

TL;DR

A Celery worker is a polling consumer. Cloud Run only allocates CPU in response to requests. Those two facts are structurally incompatible, and the incompatibility is invisible because everything works perfectly the entire time.

The fix was one environment variable. The interesting part is the four things I had to check about my own codebase before that one variable was safe, and the fact that the obvious cheaper option is broken rather than cheap.

Nothing was broken before I started, and nothing is broken now. What changed is what I'm willing to pay for, and what I gave up to stop paying it.

Most of this project was vibe coded on purpose, as a test of how far that approach goes without close architectural steering. What it produced was a conventional architecture that worked correctly and carried an operational cost nothing in the repository could have told you about.

What is a worker actually doing when there's nothing to do?

This is the question I hadn't thought carefully about, and the answer is the entire post.

A web service is easy to reason about on a serverless platform. A request arrives, the platform starts an instance if one isn't running, the instance does the work, and when the traffic stops the platform scales back to zero. You pay for the work. No traffic, no bill. The mental model is clean and it's why scale-to-zero is such a pleasant default.

A Celery worker does not fit that model at all, and it doesn't fit it in a way that is easy to miss.

A worker has no HTTP surface. Nothing can send it a request, because it isn't listening for one. What it does instead is sit in a loop, blocking on BRPOP against Redis, asking the broker over and over whether anything has shown up. Kombu, the transport layer underneath Celery, does this roughly once a second. Forever. That is not a bug or a misconfiguration, it is what a pull-based consumer is.

Now put those two things side by side. Cloud Run allocates CPU in response to requests, and scales up in response to requests. A worker never receives a request. So to keep it alive you have to tell the platform to stop doing the thing it's good at:

--min-instances=1 --max-instances=1 --no-cpu-throttling

Read those flags as a sentence. Always keep exactly one instance running. Never scale it down. Never throttle its CPU when it looks idle, because it always looks idle, right up until the moment it has something to do.

That's one CPU, allocated and billed continuously, whose entire job is to ask an empty queue if anything has happened yet.

And on the other side of the connection, the same loop is generating traffic against Redis all day long. An idle system, producing a steady stream of commands, burning through a free-tier quota to confirm repeatedly that there is nothing to confirm.

The reason this survives so long in a project is that there is no symptom. Nothing is slow. Nothing errors. Tasks run correctly the instant they're enqueued. Every test passes, every dashboard is green, and the only place the problem is visible at all is a billing page you have no particular reason to open.

The experiment underneath this

I should say plainly where this architecture came from, because it's the part of the story I find most interesting now.

I deliberately vibe coded most of this project. I wanted to test the claim that coding agents can build a full-stack app almost end to end, and more importantly to find where that approach failed when nobody was carefully steering the architecture. It's a personal project, which made it a safe place to let the experiment break things.

So: an agent wrote the Celery configuration, wired the task modules, set up the broker connection, and deployed the worker as a second service. I reviewed it, it looked right, and it was right.

Ask any competent engineer for background jobs in a Python web app and you'll get Celery, a Redis broker, and a separate worker process. Ask an agent and you'll get the same thing faster, because that is overwhelmingly what the documentation says, what the tutorials say, and what thousands of correct production systems do. It's the right answer on a VM. It's the right answer on ECS, and on a Kubernetes deployment, and on anything with a machine that stays switched on.

It's the wrong answer on Cloud Run, and it's wrong for a reason that does not appear anywhere in the code.

Which is the result the experiment actually returned, and it wasn't the one I expected. The interesting failure wasn't bad code. The generated architecture was conventional, it worked correctly, and left alone it would have kept working correctly for years. The constraint it missed was operational cost, because that information lived outside the repository.

Nothing in that repository is a clue. There's no smell to catch in review, no test that could fail, no lint rule, no type error. Every file is idiomatic. The information you need in order to notice the problem lives in a billing console, in a different browser tab, behind a login the agent doesn't have, describing a pricing model that isn't in the source tree.

An agent optimises for is this the conventional architecture for this stack. That's a good objective and it's usually the one you want. It's just not the same question as what does this cost me every month on this specific platform, and the second question is the one that mattered.

The part I find genuinely instructive is what happened next. When I brought the agent the constraint, once it knew about request-scoped CPU allocation and a personal budget, it reasoned about it perfectly well. The min-instances trap below, the Cloud Tasks alternative, the four safety conditions: that analysis came out of the collaboration, and it's good analysis. The model was never incapable of the reasoning.

It just never raised the question. Nothing prompted it to weigh a running cost, because nothing in the request mentioned one, and an agent will not go looking for a constraint you haven't told it about. That's the same finding as an earlier post of mine about tool loops, arriving from a completely different direction: the model does what the surrounding structure makes it do, and everything outside that structure is invisible.

So this is roughly where I've landed on what the human contributes in a vibe-coded project. Not the code. The code was fine. The contribution is knowing which questions the code cannot answer, and having a habit that puts you in front of the answers anyway.

Why the obvious fix is broken, not cheap

The first idea everyone has, including me, is: fine, set --min-instances=0 on the worker and let it scale to zero like everything else.

It works. Your bill goes to zero. Your queue silently never drains again.

Think about what would have to happen for that to work. The instance count is zero, so there is no worker running. For a worker to start, something would have to trigger a scale-up. The only thing that triggers a scale-up on Cloud Run is an incoming request. Nothing sends the worker a request, because it has no HTTP surface, because it's a polling consumer. There is no path from "a task was enqueued" to "an instance exists to consume it."

So tasks pile up in Redis. The API keeps accepting work and handing it to the broker perfectly happily. Stories sit in pending and never publish. Verification emails are never sent. Nothing throws, nothing alerts, and every one of those failures looks like a UI problem to whoever reports it.

Guard against this one before it happens, or spend an afternoon staring at a queue depth graph wondering which part of your code is dropping tasks. The answer is none of them.

This is the beat worth taking away from the whole post, and it generalises well past this stack: when you make a pull-based component cheaper, check that anything is still pulling.

What else was on the table

Four other options got considered properly before the one I picked.

Cloud Scheduler triggering a Cloud Run Job that drains the queue. Works, costs about nothing. Keeps Celery, keeps the broker polling, and adds up to N minutes of latency depending on your schedule. More moving parts than the problem deserved.

An e2-micro Always Free VM running the worker. Viable, and the closest thing to a real alternative. Rejected because it puts a server back in my life, one I'd have to patch and monitor, and because external egress from a VM out to a managed Redis and a managed Postgres is not the kind of free that stays free.

Cloud Tasks pushing to an HTTP endpoint. This is the right answer. I'll come back to it, because it deserves its own section rather than a table row.

Keeping the worker. Which is the problem, stated as an option, for completeness. It's worth writing this row down every time you do this exercise. Sometimes the honest conclusion is that the status quo is fine and you should go do something else.

The one-line fix

CELERY_TASK_ALWAYS_EAGER=true

In eager mode, .delay() stops being an enqueue. It executes the task immediately, synchronously, inside the calling web process. No broker round-trip, no consumer, no second service. The worker deployment gets deleted outright.

One companion setting matters as much as the flag itself:

task_eager_propagates=False

Without it, an exception inside an eagerly-executed task raises straight into the HTTP request that triggered it. A user signs up, the row is committed, the account exists, the SMTP server has a bad afternoon, and the API returns a 500 for a request that succeeded. The task failing must not be able to convert a completed write into an error response.

Why inline is safe here, and where it wouldn't be

This is the part I'd want someone to check before copying the flag into their own project, because "run your background tasks in the foreground" is not universally sound advice. It was sound in this codebase for four specific reasons, and I went and verified each of them rather than assuming.

Every enqueue already happens after the commit. This is the one that would have bitten hardest. Every call site in the codebase follows the same order:

db.commit()
db.refresh(story)
moderate_content.delay(story.id)

Commit, refresh, then fire. Because the transaction has already closed, the inline task opens its own session and reads a row that exists.

Reverse those two lines and the whole thing falls apart. With .delay() before db.commit(), an inline task runs inside the caller's still-open transaction, opens a separate session, and queries for a row that has not been committed yet. It finds nothing. It has no work to do, so it does nothing, and it does it without complaint. Under the old setup that same ordering mistake would have been survivable, because the network hop to the broker and back bought enough time for the commit to land. Async execution was papering over a latent bug, and eager mode would have torn the paper off.

The tasks are idempotent already. They were built for at-least-once delivery with task_acks_late, so running one twice is harmless. Inline execution never re-runs anything, but it costs nothing to have confirmed it.

The latency is small where it matters, and I checked the wrong half of that. moderate_content is a local better_profanity scan. No model call, no network, no IO worth naming. Inline moderation costs milliseconds and the user never perceives it. The mail path is the one with real latency, and this is where I was sloppy. I reasoned about the typical case, put a comfortable number on it, and moved on. The typical case is slower than that in practice and varies with provider and region, signup sends two emails sequentially rather than one, and none of it says anything about the tail. A condition about latency should have been stated as a bound, not as an average

The work happens during a request, which is the whole trick. Because the task executes inline, it runs while the platform has CPU allocated to serve the request that triggered it. That's the condition the entire approach depends on.

Why not just use BackgroundTasks?

FastAPI ships BackgroundTasks, and it looks like the obvious lightweight answer: schedule the work, return the response, let the task run afterwards. On a normal always-on server, that's fine.

On a scale-to-zero platform, it's a trap, and it's a quieter one than the min-instances trap.

BackgroundTasks runs your work after the response has been sent. At that moment, from the platform's point of view, the request is finished. CPU gets throttled down to near nothing. Your task doesn't crash and doesn't error, it just gets starved of the CPU it needs to make progress, and if the instance is scaled down before it finishes, it disappears mid-execution.

Inline execution works precisely because it happens before the response, while the request is still open and the CPU is still yours. The distinction between "during the request" and "after the request" carries no weight on a VM and carries all of the weight here.

The flag is load-bearing, and it fails silently

Worth stating plainly, because it's the thing most likely to go wrong for someone repeating this: once the worker service is gone, CELERY_TASK_ALWAYS_EAGER=true is not an optimisation. It is required.

Deploy without it and four call sites go back to enqueuing tasks to a broker that nobody is consuming. Story publish stays pending forever. Signup verification emails are never sent. Webhooks are never delivered. Support escalations never escalate. Every one of them fails silently, and every one of them presents as a completely different bug to whoever notices first.

There's a smaller landmine right next to it. The way you set that variable matters:

gcloud run services update ... --update-env-vars CELERY_TASK_ALWAYS_EAGER=true   # correct
gcloud run services update ... --set-env-vars    CELERY_TASK_ALWAYS_EAGER=true   # deletes everything else

--set-env-vars replaces the entire environment list rather than adding to it. Run the second one and you have just silently removed the dozen-odd other variables the service needs, including the database URL. The service then either boots broken or doesn't boot at all, and you get to find out which one on a service you were in the middle of making cheaper.

So what did it actually cost?

Nothing broke. That's the honest summary, and it's also less interesting than the trade-off, so here is the trade-off.

Retries went away. This was the real price and it wasn't a small one. Eager mode does not retry, at all. A transient SMTP failure on signup meant that verification email was lost. At the time I made the call there was no resend path either. Because this is a side project and my availability is strictly capped, I had to make a calculated trade-off between my infrastructure budget and my time budget. I chose to stop the financial bleed immediately and accept a temporarily broken edge case, rather than blocking the cost-fix while I spent weeks building the proper Cloud Tasks push-queue solution. It went straight onto the list of things to fix when time permits.

Time limits went with them, and further than I realised. task_time_limit is applied by the worker process, so with no worker it isn't loosened, it simply never runs. smtplib doesn't help either: it has no default socket timeout and blocks until the operating system gives up. That leaves the platform's own request timeout as the only remaining bound, which means a hung provider can hold a signup open until that fires and hand the user a gateway timeout on a request whose account row committed successfully. A reader pointed this out after the post went up, and he was right. The fix is two bounds rather than one: a timeout on the client so an attempt fails fast, and a total budget across all attempts and backoff, because attempts multiplied by a per-attempt timeout is the number the user actually experiences.

Task latency became user-visible. Signup carries the mail round-trip inside the request, twice, since it sends a verification email and an OTP in sequence. It sits in a flow where the user is already waiting and already expects a pause, which is the only reason the trade is tolerable at all. It's also the number I'd look at first if I were doing this again, because two sequential network calls in front of a user is a design decision I never actually made. It arrived as a consequence of one.

Task-level parallelism disappeared. Background work competes with request handling for the same process.

What I bought with that: idle infrastructure cost goes to zero, broker polling goes to zero, and there is one fewer service to deploy, secure, and monitor. Redis stays in the stack for rate limiting, caching, and the WebSocket pub/sub backplane, so nothing else in the architecture changed.

For a project with this traffic and this budget, that's a good trade. For a project where a lost email is a lost customer, it's a terrible one, and I'd rather be clear about which of those I'm running than pretend the flag is free.

What I'd build with more time

The correct answer isn't inline execution. It's push delivery instead of pull.

Replace the polling broker with Cloud Tasks, or Pub/Sub push, targeting an authenticated HTTP endpoint on the backend service that already exists:

create story ──► Cloud Tasks enqueue ──► POST /internal/tasks/moderate
                                          └─► Cloud Run cold-starts 0→1,
                                              works, scales back to 0

Every problem in this post dissolves. The task arrives as an HTTP request, which is exactly the thing Cloud Run knows how to wake up for. You keep scale-to-zero and genuine asynchronous execution and managed retries with backoff, which is the thing I gave up. Cloud Tasks' free tier covers a million operations a month, so at this volume it would also be free.

It is strictly better than both the always-on worker and the inline switch. I didn't build it because it's a re-architecture of every enqueue path in the codebase, and the inline flag was a one-line change that solved the bill that week. That's a scheduling decision rather than a technical judgement, and writing it down is how I stop myself pretending otherwise a year from now.

I wrote the revisit conditions down at the time: when task volume grows, when retries start mattering, when a task exceeds about a second of user-visible latency, or when the project is funded by something other than my own wallet.

Start smaller than this

If you're reading this with a queue somewhere and a vague sense of unease, you don't need to do any of the above today. Do the cheap part first.

Open your billing breakdown and sort by cost. That's the entire discovery step, and no amount of tooling will do it on your behalf. It's worth making it a habit rather than a reaction, because the failure mode here is a cost that never announces itself: nothing pages you, nothing turns red, and the only signal is a line item that's higher than you'd have guessed.

Then, for whatever's at the top, ask one question: does this thing get woken up, or does it wake itself up? Anything that wakes itself up on a platform that bills for allocated CPU is worth ten minutes of attention. That covers pollers, cron loops inside long-lived processes, websocket keepalives, and any consumer that blocks on a broker.

You don't have to fix it. Knowing which category each of your services falls into is most of the value, and it's the part that transfers to the next platform you use.

What carries over

1. A pull-based consumer and a request-billed platform are structurally incompatible. Not a tuning problem. The consumer never receives the thing the platform bills for.

2. When you make a polling component cheaper, check that anything is still polling. min-instances=0 on a worker is broken, not cheap, and it breaks silently.

3. "During the request" and "after the request" are different execution environments on a scale-to-zero platform, even though they look identical in your code.

4. Enqueue after commit, always. Async transport hides this bug. Inline execution exposes it immediately.

5. Before you make async work synchronous, check idempotency, latency, and ordering. Three questions, and if any answer is wrong the flag is unsafe.

6. Write down the answer you didn't build. Deferred is not the same as rejected, and future you will not remember which one it was.

7. Read the flags you deploy with as a sentence. --min-instances=1 --no-cpu-throttling says "bill me continuously" out loud, if you let it.

8. An agent gives you the conventional architecture, which is a different thing from the correct one here. It will reason about your constraints well and it will not go looking for them. The failure mode to watch for isn't bad code, it's good code carrying a constraint that lives outside the repository.

The cheapest service in your stack is the one that doesn't exist. The second cheapest is the one that only exists when someone asks it to.

I'm Ashish Kr Jha, a software engineer. I build things in production and then have to live with them, which is the part that actually teaches you something. More at ashishkrjha.dev.

The question had been a simple one. The platform we build on has an agent feature. Administrators define agents with their own tool queries, their own context rules, their own everything. They're good, and business users had opinions about what they wanted from them.

On the web client, those agents work.

On the native app, which is where the actual users are, they don't. Not a bug, not a roadmap item with a date, just a capability that exists on one client and not the other. So we asked how to close the gap, expecting either a workaround or a wait.

What we got instead was the sentence at the top of this post. The only supported way to reach those agents from the native app is to write the client yourself, as an embedded content package, running inside the host's own sandbox. Not an integration. Not a plugin. A whole application, built under someone else's rules, on a surface designed for dashboards.

So that's what this is about. Not the agents. The sandbox.

TL;DR

A locked-down host blocked fetch, blocked XHR, and blocked every form of browser storage. Its own SDK shipped a generic HTTP method, which turned out to be the sanctioned way around its own restriction. Normalise the platform differences at exactly one file, treat the async execution API as a job queue rather than a request, and be generous with your timeout ceiling when you don't control the workload.

The bug worth reading about is the poll loop, which spent a while confidently reporting failure for things that were still working.

The gap

This shape is more common than it sounds. A platform ships several clients, they don't reach feature parity at the same time, and the capability you need lives on the one your users aren't holding.

Your options when that happens are usually: wait, tell users to switch clients, or build the missing surface yourself. Waiting had no date attached. Users were on tablets all day and weren't switching. So, build.

The catch is that "build it yourself" here doesn't mean a normal web app that calls an API. It means a bundle running inside the host's own embedded content sandbox, under the host's rules.

What the sandbox takes away

Three things, and none of them are negotiable.

No fetch, no XHR, no axios. Direct HTTP from embedded content is blocked. Not CSP-blocked in a way you can argue with, just unavailable.

No storage of any kind. No localStorage, no sessionStorage, no IndexedDB. Everything lives in memory for the lifetime of the view, or it round-trips through the host's own record API.

No web root. Content is served from inside a package, so every asset path has to be relative. One base: './' in the build config, which is trivial once you know and confusing for an afternoon if you don't.

For a chat interface, that second one is the sharp edge. Chat is a stateful, conversational thing and the obvious place to keep a thread is local storage. You can't. Either you accept that a thread dies when the view unmounts, or you serialise it into a host record and rehydrate on load. We did the second, but only after building the first and discovering how much people expect a chat to remember.

The escape hatch is in the box

Here's the part I'd want someone to tell me earlier.

The host's SDK, the one you're required to load anyway, exposes two methods that together undo the restriction:

host.getSessionId()   // → { sessionId, url, isSandbox }
host.request(config)  // → generic HTTP

That's it. request is a general-purpose HTTP method that takes a URL, a verb, headers, and a body. From its point of view the platform's own API is just another endpoint.

This isn't a loophole and it isn't clever. It's the sanctioned path, and it exists for a reason worth internalising: a host that blocks network access still needs its own embedded content to reach the network. So it ships a proxy and routes everything through it, where it can be inspected, authenticated, and governed. The restriction isn't "no HTTP," it's "no HTTP we can't see."

If you're ever staring at a platform that seems to have walled off something fundamental, look for the method the platform uses itself. It's usually right there in the SDK, documented, under a name that doesn't sound like what you need.

The other half is authentication. getSessionId hands back a session token, and the documentation is slightly nervous about it. The token is described as intended for exchanging auth with external applications. Using it to call the platform's own API is a reasonable reading, but it isn't the stated purpose.

That went on the validation list as the first thing to prove. If it hadn't worked, everything downstream would have needed a proxy service and the shape of the whole project would have changed. It worked. But it was the right thing to check on day one rather than day twenty.

One file knows about platforms

The host runs on more than one platform, and the two wrap the response from request differently. One returns a string. One returns an object with the payload nested inside, under a key that varies.

There is exactly one correct way to handle that, and it's to normalise once:

async function rawRequest(path, method = 'GET', body = null) {
  const ctx = await getContext();

  const config = {
    url: `${ctx.baseUrl}/api/${ctx.apiVersion}${path}`,
    method,
    headers: {
      Authorization: ctx.sessionId,
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
    timeout: 60,
    expect: 'text',
  };
  if (body) config.body = JSON.stringify(body);

  // one platform needs a string argument; stringifying is safe on both
  const raw = await host.request(JSON.stringify(config));

  // platforms wrap the payload differently. This is the only place that knows.
  const text = typeof raw === 'string'
    ? raw
    : raw.data ?? raw.body ?? raw.response ?? '';

  return JSON.parse(text);
}

Every other file in the codebase calls a wrapper around this one and has no idea more than one platform exists. That sounds obvious written down. It is obvious. It is also the thing that decays first, because the second time you hit a platform difference you're deep in a component and it's so much faster to add a conditional right there.

Two small things worth stealing from that function. JSON.stringify on the config is unconditional even though only one platform requires it, because a rule with no exceptions survives longer than a rule with one. And session handling sits just above it: cache the session, and on an invalid-session response, clear the cache and retry exactly once before surfacing an error. Once, not in a loop.

Execution is a job queue, not a request

The agent API doesn't answer your question. It accepts it.

POST /agents/execute
→ { status: 'IN_PROGRESS', executionId: '...' }

The actual output only exists later, on a separate status endpoint, once the work finishes. So the client has to hold an execution ID, poll, and render a thinking state in between.

Three details that carry real weight:

Idempotency is your job. Every execution carries a client-generated request ID and the platform rejects duplicates, including against past executions. Generate it per execution, not per session, and make it genuinely unique:

requestId: `chat_${Date.now()}_${crypto.randomUUID()}`

Threading is a token you carry. The first turn's response includes a chat ID. Pass it into subsequent executions and the platform keeps the conversation coherent. Drop it and every turn is a stranger.

Cancellation is two things. There's a cancel endpoint on the server, and there's an AbortController for your poll loop. A stop button needs both, or you get a UI that has stopped listening to work that hasn't stopped happening.

The poll loop was wrong, and it was wrong in an interesting way

Original settings: poll every 2.5 seconds, give up after 10 attempts. About 25 seconds.

Then it started reporting failures.

Not many, and not reproducibly, which is the worst kind. Some agent actions came back in two seconds. Some took fifteen. Checking the actual execution data, a few ran past thirty.

The obvious read is "your timeout was too short." That's true, and it's also the least interesting thing about it.

Here's the real problem. The loop looked like this:

for (let i = 0; i < maxAttempts; i++) {
  const status = await getStatus(executionId);
  if (status !== 'IN_PROGRESS') return status;
  await sleep(intervalMs);
}
throw new Error('Agent execution failed');

Read that last line again. When the loop runs out, it reports failure. But nothing failed. The server never said no. The agent was still working, and would have finished, and probably did finish, into a void where nobody was listening.

The client was reporting a server outcome it had never received.

A poll loop has three possible endings and most implementations only encode two:

1. The work completed
2. The work explicitly failed
3. I stopped waiting

The third is a statement about the client, not the server, and collapsing it into the second means telling users something is broken when it isn't. Worse, it's unfalsifiable from the UI. The user sees "failed," retries, generates a new execution, and now there are two running.

The fix has two parts. Give up much later, with an increasing interval so you're not hammering the status endpoint for four minutes. And when you do give up, say what actually happened: this is taking longer than expected and is still running, not this failed.

Why the ceiling is generous

The number we landed on is 100 attempts with a growing interval. That is a lot, and it's deliberate.

This was built to be portable. Zip it, drop it into another org, configure the entry point, and it works. Which means the agents it will be talking to are ones I have never seen, built by administrators I have never met, doing work I cannot predict.

Someone smarter than me is going to build an agent that traverses four levels of related records and calls out to something slow. That agent will take a while. If my client gives up at twenty-five seconds because that was comfortable for the agents I tested against, their agent looks broken and the fault will look like theirs.

So the ceiling isn't tuned. It's generous on purpose, because I don't control the workload. That's not the same as being careful, and I'd rather be honest that 100 is a number I chose to be safely past anything I could imagine, not a bound I measured.

When you're shipping something other people will drop into environments you'll never see, the correct posture on timeouts is cowardice.

Developing outside the host

host doesn't exist on your laptop. It's injected by the platform's library at runtime, so a local dev server has nothing to call.

Same answer as every embedded-host project: shim it.

export function installHostMock() {
  if (window.host) return;   // real environment, do nothing

  window.host = {
    getSessionId: async () => ({
      sessionId: import.meta.env.VITE_DEV_SESSION,
      url: import.meta.env.VITE_DEV_BASE_URL,
      isSandbox: true,
    }),
    request: async (cfg) => {
      const c = typeof cfg === 'string' ? JSON.parse(cfg) : cfg;
      const r = await fetch(c.url, {
        method: c.method, headers: c.headers, body: c.body,
      });
      return { success: true, data: await r.text() };
    },
  };
}

Plus a dev-server proxy so local requests dodge CORS. The guard on the first line matters more than it looks: the mock must be a no-op inside the real host, because the day it isn't, you'll spend an hour wondering why production is reading your laptop's environment variables.

Worth saying: the mock is not a simulator. It gets you a working UI loop and honest network calls, and it will not reproduce the platform response-shape differences, the auth behaviour, or anything about the native runtime. Those only surface in the real thing, which is why the validation list existed before the UI did.

The validation list

Before any interface code, six things got proven:

• The session token is accepted by the target API
• All endpoints respond as documented, tested outside the sandbox first with plain HTTP
• Actions are exposed to the API at all, since the platform hides ones not explicitly flagged
• The authenticated user actually has permission to execute them
• Cross-origin behaviour on the web client
• The exact response shape from request on each platform, captured as real payloads

Two of those turned out to be non-issues. Cross-origin was fine, and the fallback proxy I'd sketched for it never got built. That's not wasted effort. It's a risk that got cheap to dismiss because it was checked early rather than discovered late.

The one that mattered was the last. Capturing the real envelopes from both platforms up front is what let the normalization live in one function instead of being reverse-engineered from bug reports over three weeks.

The general version: your riskiest assumption should be the first thing you test, and it is almost never the thing you're most excited to build.

What it turned into

The thing I didn't anticipate was what happened after the demo.

Business users are now looking at agents that were previously theoretical to them, on the device they actually use. And having seen it, they started proposing things. Could it do this. What about that. Some of those were straightforward, some needed new agents built on top of the platform's own, and several worked.

That loop is worth more than the client is. A chat window is not a hard thing to build. A chat window that puts a capability in front of the people who have opinions about it, on the device they're holding, turns those opinions into a queue of things worth building.

What carries over

Strip the vendor out and the transferable bits are short:

1. When a platform blocks something fundamental, look for the method it uses itself. Constrained hosts ship their own escape hatch, because they need one too.
2. Prove the auth path on day one. Everything downstream depends on it and it's the assumption most likely to be wrong.
3. Normalise platform differences at exactly one file and let nothing above it know they exist.
4. Treat async execution as a job queue. Idempotency keys, a thread token, cancellation on both ends.
5. A poll loop has three endings, not two. "I stopped waiting" is not "it failed."
6. Be a coward about timeouts when you don't control the workload.
7. Mock the host for local development, and don't mistake the mock for the platform.

None of that is specific to any vendor. It's what working inside somebody else's sandbox looks like, and the sandboxes are multiplying.

I'm Ashish Kr Jha, a software engineer. I build things in production and then have to live with them, which is the part that actually teaches you something. More at ashishkrjha.dev.

Once in the tool description, so the model would read it while deciding what to call. Once in the system prompt, in capitals, because the first one wasn't holding. And once in the executor, as four lines of JavaScript that simply refuse.

Only the third one works. That's most of what I learned building this.

The project was an assistant embedded in an enterprise CRM. A user asks a question in plain language, and the model answers from live records rather than from anything it was trained on. No hardcoded queries, no baked-in field lists. It navigates the data model itself.

It never shipped. The vendor released their own agents partway through, they were better suited to the domain than mine, and I stopped. The guardrails below are the part worth keeping, and they had nothing to do with that decision.

TL;DR

Publish a filtered schema artifact instead of putting the data model in the prompt. Give the model three tools: list the objects, describe named objects, query one object. Then assume every instruction you write will be ignored eventually, and enforce the ones that matter in the executor. Instructions are advisory. Code is not.

The problem: 530 objects

The org's metadata extract describes 530 objects across roughly 13,000 fields.

You cannot put that in a prompt. You also cannot hardcode the queries, because the whole point was that adding an object shouldn't mean a code change. And you can't let the model guess field names, because it will, confidently, and the query will fail in a way that costs you three hops to recover from.

The field counts are lopsided in a way that matters. The median object has 30 fields. The widest has 232. So "just fetch the schema for the object you need" is fine right up until the model picks the wrong one and drops 232 field definitions into the conversation.

Filter first, at build time

Before anything reaches the model, a Node script pulls the org's metadata extract and cuts it down:

An object allowlist. 85 API names, hand-picked, covering the parts of the CRM anyone actually asks about. That's 16% of the org. Adding an object is a one-line edit and a re-fetch, which was the design goal.

A system-field blocklist. Exact names for the obvious ones (created_by, modified_date), plus patterns for the rest: anything ending _share, _history, _feed, _tag, anything starting audit_ or system_. Audit metadata is invisible to the model because no user has ever asked a question that needed it.

Picklist values dropped entirely. This one surprised me. The enumeration of every valid picklist value was roughly 80% of the file, and it's useless. The actual value comes back attached to each record when you query it. All you'd be shipping is a dictionary of cryptic codes for the model to wade through.

What comes out the other side: 85 objects, 3,482 fields, 487 KB. Around 120,000 tokens of data model.

Which never enters a context window. The client fetches it, holds it in memory for the session, and answers tool calls from it. The model sees a list of 85 names, then the fields for the two or three objects it actually needs.

Make the graph closed

One detail I'd repeat on any project like this.

Each field that points at another object gets a references annotation, and after all objects are built, a second pass populates a referencedBy reverse index. 366 edges, with 49 objects carrying at least one back-reference. So when the model reads any object's schema, it can see what connects to it without asking another question.

The part worth stealing: a reference is only attached if the target survived the allowlist.

If an object was filtered out, every pointer to it is silently dropped. The model never sees a link it can't follow. Without that, you get a model that reads a schema, spots a promising relationship, asks for the target object, gets told it doesn't exist, and burns two hops recovering from a dead end you created.

The graph the model sees is closed under the filter. That's four lines in the build script and it removes an entire category of confusion.

Three tools

list_objects       → every object, API name plus human label
get_object_schema  → fields for one or more named objects
query_records      → records from one object

The middle one takes an array, deliberately. The model needs five objects for a typical question, and five separate calls is five hops. One call with five names is one hop. The whole cost model of a tool loop is round trips, so batching is not a micro-optimisation.

And the loop executes every tool call in a single response concurrently. The model routinely groups independent work into one turn: schemas for two objects, a query against a third. If you handle only the first call and ignore the rest, you turn one hop into three, and non-trivial questions hit the cap.

const results = await Promise.all(
  calls.map((c) => executor(c.name, c.args ?? {})),
);

That's the entire mechanism. Easy to miss, expensive to miss.

The part I got wrong: instructions are hints

Here's the rule I wanted enforced: don't ask for a schema you already have.

Obvious, right? The earlier response is still in the conversation. Re-requesting it is pure waste, and the model can see its own history.

So I wrote it in the tool description, where the model reads it while choosing what to call:

DO NOT re-request a schema you already have in this conversation.

It kept happening. So I wrote it again in the system prompt, harder:

DO NOT re-request a schema you already have in this conversation. The tool response you got earlier is still in context, so read from there.

It still happened. Less often, and never on short conversations, which is worse in a way, because it meant the failure only appeared when the loop was already long and I'd stopped watching.

So I wrote it a third time, in the executor:

const schemasReturned = new Set();

case "get_object_schema": {
  const requested = args?.objects ?? [];
  const fresh = requested.filter((n) => !schemasReturned.has(n));
  const alreadyFetched = requested.filter((n) => schemasReturned.has(n));
  fresh.forEach((n) => schemasReturned.add(n));

  result = getObjectSchema(schema, fresh);
  if (alreadyFetched.length > 0) {
    result.alreadyFetched = alreadyFetched;
    result.note = "Objects listed in `alreadyFetched` were returned in an "
      + "earlier tool response. Consult it instead of re-requesting.";
  }
  break;
}

A Set. That's it. Ask twice and you get the names back with a note instead of the payload.

The three layers do genuinely different jobs, and I'd argue you want all three:

The tool description is read at decision time, when the model is choosing what to call. Highest leverage per word, and the surface people most often leave as bare API documentation. Mine tells the model when not to call a tool: "if you already have a good guess, skip this and go straight to get_object_schema."

The system prompt sets policy for the whole conversation. Good for things that aren't about any single tool.

The executor is the only one that's true. Everything above it is a strong suggestion to a system that is, by construction, allowed to ignore you.

I'd got that backwards for a while. I kept editing prose, because editing prose feels like progress and writing a guard feels like admitting the prose didn't work. It didn't work. Four lines of code fixed what two rounds of increasingly emphatic capital letters could not.

Errors that tell the model what to do next

The same idea applies to failures. Every guard returns something the model can act on:

// object not on the allowlist
{ error: "Unknown object 'x'. Call list_objects first." }

// running outside the host application
{ error: "queryRecord unavailable. Not running inside the CRM." }

That second half of each message is the useful part. An error saying "unknown object" gets you a model guessing again. An error saying "unknown object, call list_objects first" gets you a model calling list_objects and recovering in one hop.

You are writing error messages for a reader who will act on them immediately and literally. That's a different audience from the one your usual API errors are written for, and it's worth adjusting the tone.

The token discovery

This one cost me an afternoon.

I'd set maxOutputTokens to 1024. Seemed generous, given the answers are meant to be short, under 250 words, on a tablet screen.

Responses came back truncated. Sometimes mid-sentence, sometimes empty with finishReason: MAX_TOKENS and no text at all. Which makes no sense for a 250-word answer, until you look at the usage numbers the API returns per call:

tokens in/out/thoughts: 6412/240/1180

240 tokens of answer. 1,180 tokens of reasoning. Five times more thinking than output, and on this model family the thinking counts against the same output budget.

So a 1024 cap wasn't a generous budget for a short answer. It was a budget the model could exhaust entirely on internal reasoning before writing a single word the user would see.

I raised it to 8192 and logged finishReason plus the full usage breakdown on every hop. Two things I'd do from the start next time:

Log the token split per call. Not just the total. The in/out/thoughts breakdown is what turns "why is this truncated" into an answer in ten seconds.

Filter the reasoning out of what you render. Those parts arrive flagged, and if you concatenate every text part naively you will ship "let me do a more precise count here…" straight into the user's chat bubble. One filter, easily forgotten:

const textParts = parts
  .filter((p) => typeof p.text === "string" && !p.thought)
  .map((p) => p.text);

Two kinds of budget

The loop has a hard ceiling of 10 hops. Past that it throws, and the error carries a trail of which tools ran on which hop, so you can see what the model was doing when it got stuck.

But the system prompt separately says: aim to finish common questions in 2-3 turns.

Those aren't the same mechanism. The soft budget shapes behaviour, because the model batches more aggressively when it knows it's meant to be quick. The hard cap is there for when shaping fails. One is a nudge, the other is a wall, and a loop with only one of them is either sloppy or unnecessarily rigid.

Same for the ID rule, which is a user-experience guardrail rather than a cost one:

Never show raw record IDs. If a record has an ID pointing at another object, query that object for its name and use that instead. "Dana Whitfield (12 interactions)", never "rec_8f31c0a4: 12 interactions."

Nothing enforces that in code. It's a genuine soft rule and it mostly holds, because unlike the schema-refetch rule it aligns with what the model is naturally inclined to do.

That's the distinction worth internalising: soft rules work when they push in the direction the model already leans. Enforce the ones that push against it.

Keyword tasks over a general assistant

One structural choice that paid off more than expected.

Rather than one assistant answering anything, four keyword-triggered tasks. Type brief and the system prompt gains a fragment naming exactly which objects to fetch, in what order, and what shape the answer should take. Type nothing special and you get the general mode.

Each task prompt is specific to the point of being boring:

Look up the customer id from the page context. Then, in ONE turn,
batch these schema lookups:
  • get_object_schema for: customer, interactions, orders, open_tasks, notes

Then, in the NEXT turn, emit these queries IN PARALLEL:
  • customer where id = '<id>' (limit 1)
  • interactions where customer = '<id>' order by date desc (limit 5)
  • orders where customer = '<id>' order by date desc (limit 10)
  ...

That converts an open-ended retrieval problem into a mostly-determined one. The model still resolves IDs and synthesises the answer, but it isn't rediscovering the data model on every request.

The general mode still exists for anything the four tasks don't cover. It's just slower and less reliable, which is the honest trade.

Do you need a domain-specific model for this?

The question I got asked most, and the one I'd been expecting to answer yes to.

The answer here was no, and I think the threshold sits further out than people assume. 85 objects and 3,482 fields fit comfortably into retrieval over a general model. The model doesn't need to know the data model. It needs to be able to look it up cheaply, and three tools over a 487 KB artifact does that.

What I deferred, with the trigger written down so it isn't a vibe:

Vector search over the schema. Worth it if the allowlist grows past roughly 200 objects and matching a question to the right object starts failing on names alone. At 85 it never did.

Curated domain packs. Named groups of related objects the model could request as a unit. The task prompts already name their objects explicitly, so packs only help if free-form questions start missing cluster boundaries.

A server-side proxy for the model API. Not optional for production. Client-side environment variables compile into the bundle as plain strings. Fine for a prototype key you rotate, wrong for anything real.

Writing the trigger next to the deferral is the part I'd keep. "We'll add embeddings if we need them" decays into either never revisiting it or adding it because it sounded due. "We'll add embeddings past 200 objects" is a decision you can actually check against.

What I'd keep

Strip the domain out and the transferable parts are short:

1. Publish the schema as a versioned artifact. Filter it hard at build time, and never load it into context.
2. Close the graph under your filter. No pointers to things the model can't fetch.
3. Batch by design. Array parameters, parallel execution per hop. Round trips are the cost.
4. Write the rule three times, and mean the third one. Tool description, system prompt, executor. Only the last is enforcement.
5. Make errors instructive. Say what went wrong and what to call next.
6. Log the token split per hop, including reasoning tokens.
7. Two budgets. A soft one to shape behaviour, a hard one for when shaping fails.
8. Write the trigger next to every deferral.

None of it is clever. All of it came from watching a loop misbehave and fixing the specific thing, which is the only method I know that reliably works.

This is the third of three on the same idea

Part 1 built a queryable index over a codebase so a search returns ten lines instead of a repository. Part 2 handed an agent the dependency neighbourhood around a change rather than the whole project. This one hands a model 85 objects out of 530.

Same argument three times: the win is in what you don't send. The context window keeps getting bigger and it keeps not being the answer.

• Build a TypeScript Code Graph with the Compiler API
• Code Graphs for AI Coding Agents

I'm Ashish Kr Jha, a software engineer. I build things in production and then have to live with them, which is the part that actually teaches you something. More at ashishkrjha.dev.

You ask an agent to add a rule to checkout. It opens CheckoutPage.tsx, then CheckoutButton.tsx, then checkout.css, because they all have "checkout" in the name, and after forty seconds of enthusiastic reading it writes a change in the wrong place. The actual logic was in validateOrder, which the agent never opened, because nobody named it checkoutValidation.

What gets me about this isn't the wrong edit. Wrong edits are normal; I make them too.

It's the confidence. A human who doesn't know where the logic lives asks, or hedges, or leaves a comment saying they weren't sure. An agent working from bad context does none of that. It produces something clean and plausible and completely misplaced, and hands it to you like it's finished. You can't debug uncertainty that was never expressed.

And the model wasn't the problem here. Retrieval was. The model answered the question it was given. Nobody gave it the right one.

In Part 1 I built a code graph over a TypeScript codebase: 2,795 nodes, 17,985 edges, reduced to an 873-symbol search index. This article is about pointing that graph at an agent, and what happened when I actually measured it.

Including the case where it made things worse. We'll get there.

Why "just give it the repo" doesn't work

Take a real task: add a minimum-order rule to checkout.

Search by name and you get CheckoutPage.tsx, CheckoutButton.tsx, checkoutSlice.ts, checkout.css, checkout.test.ts. Everything with the word in it, and almost nothing that matters.

What actually governs the behaviour looks like this:

CheckoutPage → calls → createOrder
createOrder  → calls → calculateOrderTotal
             → calls → validateOrder
validateOrder → used by → POST /orders, POST /order-preview

Not one of those names contains "checkout" past the first line.

The context you want isn't files with a matching name. It's the dependency neighbourhood around the behaviour you're changing, and those two sets overlap far less than feels reasonable.

This is the part I underestimated for a long time. I kept treating bad agent output as a model problem, because that's the framing everyone reaches for: better prompt, better model, more context. Meanwhile the agent was doing competent work on the wrong five files, over and over, and I was rewriting instructions at it.

This is what people have started calling context engineering, and it's where most of the leverage in agentic coding currently sits. Cursor, Claude Code, Aider's repo map and Sourcegraph all attack a version of it. A graph is just the version you can build yourself, tuned to conventions no generic tool knows about.

Retrieve a neighbourhood, not a directory

Start from a symbol and walk outward. One hop:

validateOrder
├── called by → createOrder
├── called by → previewOrder
├── calls → validateLineItems
└── calls → validateShippingRegion

Two hops:

createOrder  → used by → POST /orders
             → writes-state → checkout
previewOrder → used by → CheckoutSummary

Now assemble a packet: the target symbol, its callers, its dependencies, the routes affected, the state it touches, the nearby tests, and the architecture rules that apply.

Eight to fifteen files. Which is considerably more useful than 150 files chosen because they share a word, however impressive the token count looks.

The traversal itself is unglamorous:

function expand(graph: Graph, start: string, maxDepth = 2) {
  const visited = new Set([start]);
  let frontier = [start];

  for (let depth = 0; depth < maxDepth; depth++) {
    const next: string[] = [];
    for (const current of frontier) {
      for (const edge of neighbors(graph, current)) {
        const candidate = edge.from === current ? edge.to : edge.from;
        if (!visited.has(candidate)) {
          visited.add(candidate);
          next.push(candidate);
        }
      }
    }
    frontier = next;
  }

  return [...visited];
}

The next improvement isn't going deeper. It's being pickier about which edges you follow.

Weight your edges

For business logic, calls and writes-state matter enormously. Importing a CSS file or a shared <Button> matters approximately not at all. And yet an unweighted traversal treats them identically, which is how you end up with your design system in the context window.

const edgeWeights = {
  calls: 10,
  "writes-state": 10,
  "publishes-event": 9,
  "handles-route": 9,
  "reads-state": 8,
  renders: 5,
  imports: 2,
};

Obvious when written down. Retrieval systems fail to encode obvious things with impressive regularity.

Tell the agent what not to touch

Good retrieval isn't only about surfacing code. It's about surfacing boundaries.

Say your layering is UI → service → adapter → vendor SDK, and the agent proposes this:

// CheckoutPage.tsx
import paymentSdk from "payment-sdk";

A graph-aware check catches the new component → vendor SDK edge and rejects it before merge.

You could instead write "never import the SDK directly" in your instruction file and hope.

I've tried hoping. It works most of the time, which is somehow worse than failing outright. You stop checking, and then one Tuesday it doesn't, and the violation is already three commits deep. Prompts help. But an executable constraint has the notable advantage of not forgetting on a Tuesday.

// UI components cannot import repositories
const violations = graph.edges.filter(
  e => e.kind === "imports" && isComponent(e.from) && isRepository(e.to)
);

The cheapest rule to implement first: deprecated modules cannot gain new callers. Store a baseline count, fail if it grows. You may not get to delete the old module this quarter (you probably won't) but you can stop it spreading, and unlike most architecture rules it needs no classification logic whatsoever.

Blast radius, before the edit

An agent wants to change normalizeCustomer. The graph knows it has five direct callers, and that those callers hang off an HTTP route, a nightly import job, and two event consumers.

Target: normalizeCustomer

Direct callers:           5
Affected HTTP routes:     1
Affected background jobs: 2
Affected event consumers: 2
Nearby tests:            11

Risk indicators:
- high fan-in
- used by async worker
- crosses into the billing boundary

A crude score turns that into a ranking signal:

risk =
  directCallers * 2 +
  affectedRoutes * 4 +
  backgroundJobs * 4 +
  externalApis * 5 +
  stateWrites * 3;

Please don't turn this into a sacred number that gates your CI. The question it answers is which changes deserve extra care, not can I mathematically prove this line is dangerous. Software has never once agreed to be that cooperative.

Documentation is the other half

Some things the compiler simply cannot know.

If OrderPreviewService deliberately uses a cached price snapshot, because recalculating would make previews change after the customer approved them, no amount of static analysis recovers that reasoning. But the graph knows OrderPreviewService → calls → getPriceSnapshot, so when a task touches either symbol, that decision record can be pulled into context automatically.

Clean division of labour: the graph knows what exists and what connects; the docs explain why the weird parts are deliberate.

Keep the root doc a router

Your agent instruction file (AGENTS.md, CLAUDE.md, whatever your tool reads) should hold only what isn't derivable from the code, with a hard size limit. Mine is capped around 300 lines, which is about 6,200 tokens paid on every single session. When a section outgrows that, it's become a decision record.

Four things earn their place:

What does NOT belong where. A two-column table per folder: what belongs, and what doesn't. The negative column is the one that does the work. Every architecture doc tells you where things go; almost none tell you where things must not go, and a helper in the wrong folder is one the next person will never find, which is where duplication comes from in the first place.

A domain glossary. Business term → code term → API name. Without it, neither a new hire nor an agent can map a ticket onto a folder.

Confusing pairs, written from bugs that actually happened. In my codebase three different things are called some variant of "event," and two similarly-named entities are genuinely distinct objects that must never be merged. That section exists because both have already cost someone an afternoon.

Off-limits without discussion. Generated files, vendored code, anything external config might reference by name.

Don't start from a template. Start from your last five "why is it like that?" Slack threads and your last five review comments saying "we already have this." That's the content. It's already written; it's just scattered across conversations nobody can search.

Decision records that end in "Do not"

Not every decision deserves a record. The ones that do are the decisions a reasonable engineer will eventually try to simplify. Usually on a Friday, usually with good intentions.

So every ADR I write ends with a Do not section, phrased as the sentence that engineer would say to themselves:

# ADR: External API access stays behind adapters

## Context
The vendor SDK has unstable response shapes and inconsistent errors.

## Decision
Feature code calls typed adapter functions.

## Do not
Do not import the SDK directly inside a feature module,
even if your new feature only needs one endpoint.

That last section is the difference between a decision log and a guardrail. A normal ADR explains a choice to someone who reads it. A "Do not" line intercepts someone who was never going to read it, because it's the phrase they'll grep, or the phrase retrieval surfaces at the moment it matters.

Two rules keep this honest. ADRs are append-only. Supersede, never edit, so a record is either current or explicitly historical with no third state where it quietly disagrees with the code.

And now the embarrassing part

The second rule is that these documents rot, and a confidently wrong router is worse than none at all.

I can be specific about this, because when I re-ran my measurements I audited the docs against the code at the same time. Here's my own paperwork:

Every one of those was written by someone careful. I know, because it was me. I'd written the negative-space table and the append-only rule in the same sitting, feeling quite good about myself.

Nothing in my process caught any of it. There was no moment where the docs announced they'd gone wrong. They just sat there, confident and slightly false, for months.

The second row is the one that stings. A "not done yet" list advertising a gap that was closed months ago will send the next person off to rebuild something that already works. That isn't documentation sitting there being harmlessly stale. That's documentation actively wasting someone's afternoon.

Tie doc review to convention changes rather than the calendar, and audit the docs whenever you regenerate the graph. The graph is the only thing in your repo positioned to catch your prose lying.

Correct for the model's priors, too

One more failure mode, running in the opposite direction.

The first review my instruction file got flagged that the model kept adding memoization everywhere. The reviewer's diagnosis: its training data skews toward older React, where you had to. Newer versions handle much of it automatically.

That isn't the model lacking knowledge of my codebase. It's the model having too much knowledge, of the wrong vintage, applied with total confidence.

So an instruction file has two jobs. It encodes what's true about your repository, and it corrects what the model assumes about your framework. The second kind is easy to skip because it doesn't feel like documentation. It feels like arguing with a very self-assured junior. Write it down anyway:

## Version-specific: override your priors

- React 19: do not add useMemo/useCallback defensively.
  The compiler handles most of this. Memoize only with
  a measured reason.

Both kinds go stale, in opposite directions. Your code drifts from your docs. The model's assumptions drift from your framework. The router file sits between them and is the only thing watching either.

Diff the graph after the patch

Before: Feature → Service → Adapter → External API. After: same chain, plus a shiny new Feature → External API.

It compiles. The tests pass. Nothing is red. And an architectural boundary just moved.

The graph delta catches it:

Graph delta

+ CheckoutPage → calls → validateMinimumOrder
+ validateMinimumOrder → reads-state → pricingRules
- CheckoutPage → imports → legacyValidation

No new cross-layer imports.
No new dependency cycles.

Easier to review than a 600-line diff you're scrolling through at 5pm hoping the architecture reveals itself.

The general principle: check effects, not just generated text.

The whole loop, assembled

Put the retrieval half and the verification half together and you get something that looks less like "an AI writes code" and more like a pipeline with the model as one stage in it.

Steps one to four decide what the model is allowed to see. Steps six to eight check what it did with that. The agent itself only ever occupies step five, which is a considerably smaller share of the system than the marketing around agents would have you believe.

That framing is useful when something goes wrong, because it gives you somewhere specific to look. Bad output means either the packet was wrong or the model was wrong, and those live in different stages with different fixes.

So what does it actually save?

Time to stop asserting and measure.

I took six real discovery questions from my own codebase and ran each two ways. Through the symbol index, and through the exploration you do without one. Orient in the tree, grep a guess, grep again because the first guess missed, open files to confirm.

Real commands, real output, three repetitions, median reported.

Cells read with index / without.

81% less output for the model to read. 13 fewer tool calls.

The call count is what drives cost, because every call is a round trip that re-sends the whole accumulated conversation as input. Counting the final answer turn: 14 round trips against 27. Model those at current large-model pricing and the cost difference lands near 49%.

I swept the assumptions. Harness context from 4k to 80k tokens, output per turn from 200 to 4,000, latency from 3 to 20 seconds. It stays in a 48-51% band, because the result is driven by measured call counts rather than my guesses.

Now the caveats, which matter more than the percentage.

The without-index path is a modelled sequence, not an observed agent run. I wrote those commands based on what unaided search looks like here. A sharper agent might do the first task in two calls. A flailing one might take eight. The output volumes are real measurements of what those commands return. The baseline's shape is my judgement.

Token counts come from an estimator, not a token-counting endpoint. Call it ±10–15%. Applied identically to both sides, so the ratio holds even if absolutes drift.

And this prices discovery only. It doesn't price the thing the index mainly exists to prevent, which is an agent writing a second formatDate because it never found the first. That cost lands in review, or next sprint, or in a bug six months out. No single-session benchmark catches it.

Read 49% as a floor.

And when it makes things worse

Here's the number I suspect most posts like this quietly skip.

The instruction file loads every session whether anyone searches or not. 6,179 tokens, paid up front, every time. Against an average saving of about $0.076 per discovery task, it pays for itself within the first task of a session.

But the worst realistic case, with the instruction file loaded and the index never queried and the agent grepping anyway, comes out 9.1% more expensive than having no toolchain at all.

That's the downside bound. One avoided duplicate helper repays it many times over, so I'll take that trade all day. But if your own benchmark doesn't contain a number like this, you haven't finished measuring. You've finished marketing.

You may also find plain lexical search handles most of your tasks fine. Good. Use the graph where structure genuinely helps. The goal isn't to justify the elaborate thing you built.

Separate the retriever from the agent

This distinction does more work than anything else here.

When an agent makes a bad change: was the model weak, or did retrieval never surface the critical dependency? Different failures, different fixes. Track them together and every failure becomes "improve the prompt," including the ones caused by the agent never seeing the file.

On row three the model failed because the retriever never surfaced the shared rule. No amount of prompt engineering fixes that, though I'm sure someone has tried for a week.

Start with retrieval, not autonomy

If I were introducing this somewhere new I wouldn't begin with an agent editing production code.

Start here: developer asks a question → system finds relevant symbols → system shows the neighbourhood → developer picks what to read. Then: agent proposes context → developer reviews → agent proposes a patch. Automate further only after you've measured retrieval quality.

You get useful tooling immediately, and it survives the model layer changing underneath you, which it will, roughly every four months. The graph describes your repository, not somebody's API.

Quick answers

Is this just RAG for code? It's the retrieval half, with structure instead of embeddings. Chunk-and-embed finds text that reads similar. A graph finds code that's actually connected. Good systems use both.

How is this different from a repo map? A repo map is usually a flat summary handed over up front. A graph is queried per task, so context scopes to the change instead of the codebase.

Do I need this with Cursor or Claude Code? On a small codebase, probably not. Their retrieval is good. It starts paying off when your repo has conventions no generic tool knows, which is exactly what those framework-specific edges encode.

Does this work outside TypeScript? The concepts do. The implementation leans on the TypeScript type checker for cross-file resolution; you'd need an equivalent.

Building the graph itself

This article assumed the graph exists. For the implementation, covering Program, TypeChecker, symbol resolution, framework-specific edges and intent search, start with Part 1:

Build a TypeScript Code Graph with the Compiler API

The takeaway

The best use of a code graph in AI-assisted development isn't a prettier architecture diagram. It's controlling context.

What should the agent read. What should it not touch. What else might this change break. Which tests matter. Did this patch just move a boundary.

That's a retrieval and verification layer around the agent, and a far better foundation than "AI that can read the repo," which is not a strategy so much as a hope with a large context window.

The part I didn't expect: almost none of this work was about AI. Naming things findably, writing down which decisions are load-bearing, admitting where the docs had drifted. That's the same work that makes a codebase survivable for the humans in it. The agent just made the cost of skipping it visible, and put a number on it.

Which, honestly, is more than any of my previous attempts to care about documentation ever managed.

I'm Ashish Kr Jha, a software engineer. I build things in production and then have to live with them, which is the part that actually teaches you something. More at ashishkrjha.dev.

I have. More than once, in the same codebase. And once, on a helper I had written myself eight months earlier, under a name I no longer remembered choosing. That's the one that stayed with me.

There's a very particular flavour of embarrassment in that. Not "I didn't know the codebase," which is forgivable. More like finding out you've been introduced to yourself at a party.

And the genuinely infuriating part is that searching wouldn't have saved me. The function was there. It was called something I'd never have guessed in a hundred tries.

That's the problem this article is about. Not "how do I search my code" but something harder: how do I ask my codebase a question and get a real answer?

Three questions in particular:

1. Does this already exist?

2. Where does this code belong?

3. What will I break if I change it?

Grep can't answer any of them properly. But the TypeScript compiler can, and it's already sitting in your node_modules.

First, why grep runs out of road

Say you've got this import:

import { calculateOrderTotal as getCartValue } from "@/pricing";

const total = getCartValue(cart);

Now search for calculateOrderTotal. This file won't come up. The function is here, it's being called right now, but it's wearing a different name.

And even without the alias, @/pricing is almost certainly a barrel file re-exporting from somewhere else. Barrel files are wonderful for writing imports and actively hostile to everything that happens afterwards. The real declaration is two hops away from anything you typed.

Grep works on text. The TypeScript type checker works on meaning. Ask it what getCartValue refers to and it walks back through the alias, through the barrel, and hands you the actual declaration.

That difference is the whole article. Text search tells you a string appears in twelve files. The compiler tells you which symbols call which function. Only the second one is something you can safely refactor.

Why I actually built this

For a while I treated this as a personal failing. Learn the codebase better. Read more of it. Keep a list.

Then I watched a new engineer join and spend most of their first fortnight asking questions I couldn't answer cleanly either. Where does this belong, does something like this exist, what happens if I change this. I'd been there two years and I was guessing. Confidently, and often correctly, but guessing.

That's when it stopped feeling like a memory problem.

There's a threshold a codebase crosses where nobody holds it in their head anymore. Not the tech lead, not the person who wrote the first commit. Past that line you start making changes with a quiet undertone of I think this is fine, and you ship it, and mostly it is fine, and the times it isn't you find out from someone else's bug report.

I didn't want a better memory. I wanted to stop guessing.

What this looks like when it works

Before we build anything, here's the payoff:

$ node find-symbol.mjs "convert date to utc"

1. parseIsoTimestamp        dates/parseIsoTimestamp.ts
2. normalizeServerDate      dates/normalizeServerDate.ts
3. formatUtcDate            display/formatUtcDate.ts

I typed what I wanted. It found things named nothing like it, in about a third of a second, and I have never once had to remember what any of them were called.

Some numbers from the codebase I built it on, so you know the scale we're talking about:

The domain is anonymized and the examples below are generic, but every number is real.

Step 1: Ask TypeScript for a Program

A Program is TypeScript's view of your whole project: every file, resolved with the same config your app builds with.

import ts from "typescript";

const configPath = ts.findConfigFile("./", ts.sys.fileExists, "tsconfig.json");
if (!configPath) throw new Error("No tsconfig.json found");

const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, "./");

const program = ts.createProgram({
  rootNames: parsed.fileNames,
  options: parsed.options,
});

const checker = program.getTypeChecker();

Using the project's own tsconfig.json matters here. Your path aliases and allowJs settings need to match what actually compiles, or half your imports won't resolve.

Then walk the files:

for (const sourceFile of program.getSourceFiles()) {
  if (sourceFile.isDeclarationFile) continue;
  if (sourceFile.fileName.includes("node_modules")) continue;
  visit(sourceFile);
}

function visit(node: ts.Node) {
  if (ts.isFunctionDeclaration(node) && node.name) {
    addNode({
      id: `function:${node.name.text}`,
      kind: "function",
      name: node.name.text,
      file: node.getSourceFile().fileName,
    });
  }
  ts.forEachChild(node, visit);
}

You now have a list of every function in your project. Useful, but it's still just a list.

Tip: keep TypeScript AST Viewer open in a tab while you write this. Paste in a snippet, see exactly what node types come back. It'll save you an hour of guessing.

Step 2: Resolve symbols, not strings

Here's where it gets interesting. When you hit a call expression, ask the checker what's being called:

if (ts.isCallExpression(node)) {
  const symbol = checker.getSymbolAtLocation(node.expression);
}

But if that call came through an import, you've got an alias. A pointer, not the thing itself. So unwrap it:

function resolveSymbol(symbol: ts.Symbol | undefined) {
  if (!symbol) return undefined;
  if (symbol.flags & ts.SymbolFlags.Alias) {
    return checker.getAliasedSymbol(symbol);
  }
  return symbol;
}

That flag check isn't optional, and I found that out the way everyone does. getAliasedSymbol throws if you hand it something that isn't an alias. Not returns null, not returns the original. Throws. In a codebase with barrel files you'll hit both cases inside the same file, so guard it, or spend twenty minutes wondering why your build script dies on file three every single time.

Now record the relationship:

const resolved = resolveSymbol(symbol);
const declaration = resolved?.declarations?.[0];

if (declaration) {
  addEdge({
    from: currentSymbolId,
    to: symbolId(resolved, declaration),
    kind: "calls",
  });
}

You're now storing a link between two real declarations instead of two strings that happen to match. Everything else builds on this.

Step 3: Keep the data model boring

type NodeKind = "file" | "function" | "component" | "hook" | "state" | "package";

type EdgeKind =
  | "imports" | "calls" | "renders"
  | "uses-hook" | "reads-state" | "writes-state";

interface GraphNode {
  id: string;
  kind: NodeKind;
  name: string;
  file?: string;
}

interface GraphEdge {
  from: string;
  to: string;
  kind: EdgeKind;
}

Write it out as { "nodes": [], "edges": [] } and stop. I know "knowledge graph" sounds like it deserves something fancier, but plain JSON has one enormous advantage: it exists today, and you can query it with Array.prototype.filter.

Mine comes out at 5.5 MB. Gitignore it. We'll commit something much smaller in a bit.

Step 4: Teach it about your codebase

Everything so far is generic. If you stop here you've built a dependency graph, which dependency-cruiser and Madge already give you for free, and which you've just spent a weekend reinventing. Don't stop here.

The value comes from two functions you write yourself.

classifyFile(path) maps your folder conventions onto node kinds. src/hooks/ means hook, src/redux/slices/api/ means API client. Get this wrong and every query afterwards returns noise, because "show me the components that read this state" depends on the graph knowing what a component is.

detectFactoryKind(initializer) catches the things your framework creates through function calls. The AST just sees a const, so without help your graph is full of opaque constants where the interesting nodes should be. I detect createAsyncThunk, createSelector and createSlice. Yours might be defineStore, createMachine, or a DI registration.

Both are short, forty lines or so. They're also the difference between a generic import graph and a map of your system.

Now you can add edges nobody else could give you. When the walker sees this:

const cart = useAppSelector(state => state.cart);

it emits CheckoutPage → reads-state → cart. And when it sees a thunk:

export const refreshCart = createAsyncThunk("cart/refresh", async () => { ... });

it emits refreshCart → writes-state → cart.

Something I didn't expect. Those two state detectors produced 320 edges out of nearly 18,000, under 2% of the graph. They're also the ones people query. The compiler gives you thousands of edges for free; the handful you write yourself carry most of the weight.

The bug it found in its first week

I want to tell you about this one, because it's the moment the tool proved itself and it wasn't a feature.

My reads-state detector keys off the state shape, state.invoiceTemplates, plural. My writes-state detector keys off the name passed to createSlice({ name }), which turned out to be invoiceTemplate, singular.

Same slice. Two different names depending on which direction you asked.

My first reaction was that my detector was broken. My second, after ten minutes of checking, was the slightly cold realisation that it wasn't. The codebase had been carrying that inconsistency for years, and every one of us had walked past it.

Nobody had spotted it because no single file shows you both sides. You'd have to open the slice definition and a component that consumes it, at the same time, while specifically hunting for a mismatch that you have no reason to suspect exists. Nobody does that. Nobody has ever done that.

Expect a few of these. A graph that surfaces your naming inconsistencies is working correctly, even when the first thing it tells you is embarrassing.

Step 5: Make symbols searchable

A node gets far more useful once it carries more than a name:

{
  "id": "function:parseIsoTimestamp",
  "name": "parseIsoTimestamp",
  "kind": "function",
  "module": "dates",
  "summary": "Convert an ISO timestamp into UTC epoch milliseconds",
  "signature": "(value: string) => number"
}

The checker infers most of that for free, which is the nice part. You get a decent search index without asking anyone to maintain a catalog by hand.

One honest number before you get excited: in my index, 91% of symbols have a type signature and 24% have a written summary.

Signatures come from the compiler. Prose comes from humans. You can guess which one shows up reliably.

So if you want better search results cheaply, don't set out to document everything. Add doc comments to the shared helpers only, the forty things people keep re-implementing. That's where the return is.

Step 6: Search by intent

Now the search itself. The key idea is tokenization: toEpochMs and to_epoch_ms both break down into ["to", "epoch", "ms"]. That's what lets someone search for a thing they want and find a function named nothing like it.

This is the case grep structurally cannot handle. normalize_date and clean_timestamp share zero characters, so no regex will ever connect them, but both might be exactly what you meant.

The scorer is a weighted sum, and I'd encourage you to keep yours equally dull:

function scoreSymbol(symbol: SearchableSymbol, query: string) {
  const q = normalize(query);
  const name = normalize(symbol.name);
  const summary = normalize(symbol.summary ?? "");

  let score = 0;

  if (name === q) score += 1000;        // exact name
  if (name.includes(q)) score += 60;    // name substring
  if (summary.includes(q)) score += 25; // summary substring

  const queryTokens = tokenize(q);
  const nameTokens = new Set(tokenize(name));
  const summaryTokens = new Set(tokenize(summary));

  for (const token of queryTokens) {
    if (nameTokens.has(token)) score += 20;
    if (summaryTokens.has(token)) score += 6;
  }

  return score;
}

Module match adds 15, path match 10. The exact numbers barely matter. You'll tune them against your own repo within a day of using it.

Wrap it in a CLI with no dependencies:

node find-symbol.mjs "convert date to utc"
node find-symbol.mjs --kind component "loading spinner"
node find-symbol.mjs --module src/redux "thunk"

The part that makes it cheap

Here's the bit I like.

That 5.5 MB graph reduces down to a 717 KB index of 873 symbols. Run a token counter over it and it's roughly 248,000 tokens of structural information about the codebase. The full graph is closer to 1.9 million.

None of it is ever loaded into a context window. Not once.

A search reads it from disk, ranks it in about 300 milliseconds, and prints ten lines.

That ratio, two million tokens on disk and ten lines in the answer, is the entire argument for building structure instead of stuffing more files into a prompt. It's also why this works fine for humans who don't have a context window at all.

Commit the index, gitignore the graph. And pretty-print it rather than minifying. It changes on every edit and turns up in most diffs, so a reviewer is going to see it. A readable diff is the difference between "fine, whatever" and "can we please delete this thing." If merge conflicts get annoying, a merge=union gitattribute helps.

Do you need embeddings for this?

Not to start. Embedding search does help when the query and the symbol share no vocabulary at all, and that case is real.

But a lexical scorer is fast, local, explainable, free to run, and tunable in an afternoon. No vector database, no model dependency, no API key, no monthly bill for a service that indexes 873 functions.

Add embeddings later, once you've collected actual searches where the ranking failed. Otherwise you're solving a problem you haven't met yet, which is a considerably more expensive hobby than it sounds.

Same answer for graph databases. My entire query surface is graph.edges.filter(...) run through node -e. Reach for Neo4j when you need multi-repo traversal or interactive exploration, not because a diagram had arrows in it.

Keeping it honest

An index that was accurate three months ago is a historical document. Regenerate it in one of these places, best first:

1. Editor or agent post-edit hook. Freshest, zero ceremony, but only covers people using that tool

2. Pre-commit. This is the one that keeps it correct for the whole team

3. Manual, before searching. Costs 13 seconds

4. CI on merge. Fail if regenerating produces a diff

Whatever you do, don't put regeneration on a sprint cadence. It goes stale during the sprint, which is precisely when the duplicates get written. You'd be building a tool that is reliably most wrong at the exact moment anyone needs it.

My post-edit hook is 25 lines, and the most important line in it is this:

} catch {
  // Never disrupt the workflow. Swallow errors silently.
}

A background hook that can fail loudly will be switched off within a week, by you, irritably, mid-task, the third time it interrupts something. It either works invisibly or does nothing at all. Both outcomes are survivable. Popping up in someone's edit loop is not.

Where this doesn't help

Worth being upfront. The graph misses runtime dependency injection, string-based event names, dynamic imports, reflection, database relationships and external config.

The biggest gap is simpler: it only sees TypeScript. SQL, Python, templates, config files: all invisible, along with any coupling that runs through them. If a chunk of your logic lives in stored procedures, the graph is describing half your system while looking complete.

Treat it as a useful model, not an oracle.

Start smaller than this

You don't need everything above to get value. Here's the version that fits in a day:

1. Build a Program

2. Index files and exported symbols

3. Resolve imports and calls

4. Write classifyFile for your folders

5. Add one framework-specific edge, whichever coupling your team keeps asking about

6. Save as JSON, gitignore it, commit a reduced index

7. Add one command people run before writing shared code

Steps 1–4 are an afternoon. The rest is another one. On a 771-file tree the whole rebuild takes 13 seconds, so the loop while you're tuning detectors is quick.

Then watch what happens. Do people find existing helpers? Are fewer near-duplicate utilities landing? Which searches return junk?

The graph is only infrastructure. Its value comes entirely from the questions people actually ask it.

What I got out of it wasn't really the search command, in the end. It was that the codebase stopped feeling like something I was negotiating with. Changes I'd have approached carefully, I could now approach quickly, because I could see what was on the other side of them.

That's a small thing to say and a large thing to have.

Quick answers

Do I need a graph database? No. JSON and array filters go a long way.

How long does the build take? 13.1 seconds on 771 files. Fine on a save hook, too slow per keystroke.

Does this work for plain JavaScript? Partly. allowJs pulls .js files in, but without annotations the symbol resolution is much weaker.

Is this just an AST? No. An AST gives you syntax inside one file. The type checker resolves meaning across files, working out which declaration an identifier points at. That's the part that matters.

Should I use ts-morph instead? If you're writing codemods, yes, it's a much nicer API. I went with the raw Compiler API because the only import is typescript, which the project already had, so the script copies into another repo with no install step. That's the whole trade: a few hours of extra plumbing for zero new dependencies.

Next: handing this to an AI agent

Once your codebase is nodes and edges, search is only the first thing you can do with it. The same graph can decide what an agent should read before editing a function, which routes a refactor might touch, and whether a change just crossed an architecture boundary.

I measured that, including the case where it costs more than doing nothing:

Code Graphs for AI Coding Agents: Better Repository Context and Safer Refactoring

I'm Ashish Kr Jha, a software engineer. I build things in production and then have to live with them, which is the part that actually teaches you something. More at ashishkrjha.dev.

The CSS Box model is a box that wraps around every HTML element. The term "Box Model" is used when talking about design and Layout. It consists of few things: Margin, Padding, Borders, and the Actual content.

All the things in a box model give HTML a structure. We will discuss some of the options given to us for this model

Borders

Borders can be applied to most boxes in HTML. Borders have parameters such as

• border-width : This decidess what the width of the border will be

• border-style: This parameter helps us to determine the style of the border

• border-color: We can change the color of the border using this parameter

• border-radius: This is use to curve the edges and can help us to make the UI look more elegant or make rounded shapes.

  We can use the various options these parameters provide us. We can use these parameter on all four sides of the container. For more in-depth knowledge refer here

Margin

Margins are like their name suggests, consider the margins of your notebook. We try to keep things within the margins of the notebook. Similarly in CSS when we use margin it is applied on the outer side of the container. It can be use as

• margin: This applies the margin evenly on all four sides of the container

• margin-left : This applies the margin at the left side of the container

• margin-top : This applies the margin at the top side of the container

• margin-right This applies margin at the right side of the container

• margin-bottom: This applies the margin at the bottom side of the container

Warning: Overuse of Margin may lead to margin-collapse which messes up the entire flow of the layout.

It is best to avoid using margins in all places. Margins can affect the layout of other containers depending on where you use it. For more in-depth knowledge refer here

Padding

Padding is the gap inside, between the border and the content. It's like a cushion that separates the border and the content inside the container. Padding doesn't not impact anything outside of the container. It is essential to the layout.

Just like the margin, we can apply padding on all four sides of the container or just one side depending on the requirements of the UI. It can be applied as

• padding: This applies the padding evenly on all four sides of the container

• padding-left : This applies the padding at the left inner side of the container

• padding-top : This applies the margin at the top inner side of the container

• padding-right This applies margin at the right inner-side of the container

• padding-bottom: This applies the margin at the bottom inner-side of the container

For more in-depth knowledge refer here

Scope

The scope is the accessibility of variables, functions, and objects in some particular part of your code during runtime. In other words, scope determines the visibility of variables and other resources in areas of your code. Scopes are layered in a hierarchy, so the child has access to the parent's scope but not the other way around.

Think of it as the relationship between child and parent, the child can ask or take an ice cream or chocolate from the parents but not the other way around (I mean you can but...)

This example should give you a better understanding. Let's dive into the different types of scope in Js

What is a Global Scope?

Global scope is the default scope for running all the code in js and everything runs in this scope.

let globalVariable = 'test1'

function test() {
//some code
}

In the above example the globalVariable with the value of test1 is in global scope. In HTML the global scope refers to the window Object

• Module Scope: This is the scope of the modules in the code. You must have imported some modules if you have worked with any frameworks of Js

What is a Function Scope?

Function Scope is the scope created using a function

function test() {
let number = 45
console.log(number)// this will print the number 45 when the function is called
}
test()
console.log(number) //this will throw an error of the number is not defined

In the above example, you can see we cannot access the variables from outside the function if they are declared inside the function. But functions inside the function test() can access the variables of the parent function. Sometimes it is also referred to as Lexical scope.

How do let and const act in terms of scope?

There are let and const which work in block scope.

Block Scope It is a scope created by opening { and closing with }

{
    let num = 25
    const tea = 'tasty'
    console.log(num) // 25
    console.log(tea) // tasty
}
console.log(num) // num is not defined
console.log(tea) // tea is not defined

There is another keyword called var which has a function or global scope but it is not advisable to use this var keyword for declarations.

What is a scope chain?

Js engine uses a scope to find the exact location or accessibility of the variables and that particular process is called Scope chain. It means that one variable has a scope used by another variable or function having another scope.

Single Thread

Those of you who have been working with Js for a while would have come across the term called Single Thread. This term is just used to refer to a way javascript reads code which is one or single line at a time. Javascript is a language that runs one line of code at a time and waits until that line is complete and is ok and moves to the next line.

If the line needs time to execute it moves to the next line by default but to stop if from moving we can use async/await and wait until the current line is executed completely. We might have to do this because the results of the current line might be required for future lines of code. This happens because Javascript uses something called call stack which we will discuss in the next section

Call Stack

If you know the Data Structure of stack which follows LIFO, call stack is works just like that. However if you don't know the Data Structure Stack worry not, we got you covered.

Explain call stack.

Imagine a pile of books, a very tall pile of heavy books. If you try to get something at the bottom it will be very difficult and you might end up crashing the tower of those heavy books. So what do you do? You take the book on top and remove it and keep doing this until you reach your desired book. Same thing is happening in call stack. The term LIFO stands for Last In First Out, which simply means the book you kept last on the top of the pile needs to go out first

function A(){
    B()
    console.log(`I am Function A`)
}
function B(){
    C()
    console.log(`I am Function B`)
}
function C(){
    console.log(`I am function C`)
}
A()

Now in the above example you can see the function C ran first then function B and then finally function A. Image below explains this further.

The blocks in the above image are functions that were pushed into the call stack.

• First the program was scanned and it saw only function A is being called so it went to Function A
• In Function A it saw the call for Function B before the console.log could execute so it went to Function B and added it in the call stack, and from there to Function C and added it to the call stack.
• Entire functions are loaded and stacked on top on one another and so we execute the one at the top, In this case its Function C.
• After the execution of Function C, the next function in the call stack was Function B so it went ahead and executed the console.log there.
• And finally, it executed the last function remaining in the call stack which emptied the call stack.

Hoisting

JavaScript Hoisitng refers to the process by which the interpreter moves the declaration of functions, variables to the top of their scope before the code execute.

This allows Functions to be safely used before they are declared but variables and classes are hosted differently.

A general rule which helps me to track hoisting process is :

• Functions are scanned and stored in memory or made available for future use
• Variables are scanned and made undefined

Function Hoisting

A(5)
function A(num) {
    console.log('\n')
    console.log(num*num)
    console.log('\n')
}

As you can see in the example that the function A() is being called before the declaration. When the Javascript interpreter scanned the program it saw a function A() and it knew there is a function called A(). Without hoisting we would have to call the function after it is declared.

Variable Hoisting

According to the rule mentioned above Variables used before declaration will return undefined value

console.log(num)
var num  = 9
num = 8*8
console.log(num)

In the above example you can see the when we use variable before declaration it returns undefined. After which we declare it and give it a value of 9 and then change that value to 8*8 and console.log the value which returns 64 which is the result of 8*8.

This is example case but if we use let instead of var, it would throw an error on the first line saying num is not defined

Well, In programming it is just a collection of some similar or non-similar data. In Javascript, there is no restriction on array type. For example

int arr[] = { 10, 20, 30, 40};

the above array contains only numbers and is in the syntax of C++ language, as you can see the type int has been mentioned.

let arr = [ 'Cars', 4, true, ['this' ,'is' ,'subarray']]

However, In Javascript, we don't need the type declaration, which is a good or bad thing depending on the situation. The above example demonstrates the declaration of an array. In Programming arrays play a vital role. Javascript has provided us with multiple functions to make our life easier in development. In this Article we will be discussing the various aspects of the array functions in Javascript.

Declaration Using Constructor

We can declare array via above method called literal notation or constructor

const numbers = [1,2,3,4,5]

Another method to declare the array using the constructor

const  numbers = new Array(1,2,3,4,5)

We can also declare array length like

const numbers = new Array(5)

Static Array Methods

Array.from()

We can use static array methods to create a new arrays from some data we have. The syntax is Array.from()

Array from a String:

const name = 'mango'
console.log(Array.from(name))

Array after performing some operation: The Syntax is Array.from(array, function)

const arr = [1,2,3]
console.log(Array.from(arr, x => x*x))

Array.isArray()

This Array function checks if the given parameter is an array or not. It returns true if it is an array otherwise it returns false

const arr = [1,2,3];
const name = 'mango';
console.log(Array.isArray(arr));
console.log(Array.isArray(name));

Array.of()

The Array.of() method creates a new Array from the arguments given regardless of type.

console.log(Array.of('travel'));
console.log(Array.of(1,2,3));

Instance properties

Array.length

This is a widely used property that gives us the length of the array, array.length

const numbers = [1,2,3,4,5,6,7,'q','w','4',3]
console.log(numbers.length);

Instance Methods

Array.at()

This method returns array item at a given index, It also accepts negative integers as arguments and counts back from the last element. Array.at(), This is a fairly new method so it might not be available for you in your environment.

const numbers = [1,2,3,4,5,6,7,'q','w','4',3]
console.log(numbers.at(5));
console.log(numbers.at(-8));

Array.concat

This is a method which concatenates two different arrays into one array. array1.concat(array2)

const numbers = [1,2,3,4,5,6,7]
const numbers2 = ['q','w','4',3]
console.log(numbers.concat(numbers2))

Array.copyWithin()

The copyWithin() method copies part of an array to another location in the same array and returns it without modifying its length. It can take 3 arguments but atleast one argument must be present

array.copyWithin(target,start,end)

const numbers = [1,2,3,4,5,6,7,'q','w','4',3]
console.log(numbers.copyWithin(0,3,4))
console.log(numbers.copyWithin(0,3,7))

Array.entries()

This method gives us the index/value of the array elements. We can

const num = ['a','b','c','d']
for(const [index,element] of num.entries()){
    console.log(index,element)
}

Array.every()

This method checks if all the elements of the given array satisfies the condition. It returns true if all elements meet the condition otherwise false. We have taken a simple even number example

const isEven = (value) => value%2===0
const arr1 = [2,4,6,8]
const arr2 = [2,4,6,7]
console.log(arr1.every(isEven))
console.log(arr2.every(isEven))

Array.fill()

This is a method used to change array elements to a static value, it modifies the original array. General syntax

fill(value,startIndex,endIndex)

Here start Index and end index are optional, without these all elements will be replaced by the value. Also just like the .at() method we can use negative integers to start from the end of Array

console.log([1,2,3,5].fill(4));
console.log([1,2,3,5].fill(4,1))
console.log([1,2,3,5].fill(4,1,2))
console.log([1,2,3,5].fill(4,-3,-2))
console.log(Array(4).fill(4))

Array.filter()

This returns new array containing all the elements of the calling array for which the filter condition is true. It takes a callback function to check the condition.

const num = [1,2,3,4,5,6,7,8,9]
console.log(num.filter(ele => ele%2!==0))

Array.find() and Array.findLast()

The find() method returns the first element in array which satisfies the given condition. If no values found it returns undefined

The findLast() method returns the last element in array which satisfies the given condition instead of the first like in find(). If no values found it also returnsundefined`

//example contains only find() 
// findLast() also works same but returns last element.
const num = [1,2,3,4,5,6,7,8,9]
console.log(num.find(ele => ele>7))// check for number greater than 7

Array.findIndex() and Array.findLastIndex()

The findIndex() method returns the index of the first element in the array which satisfies the given condition. If no elements are found, it returns -1.

The findLastIndex() method returns the index of the last element in the array which satisfies the given condition. If no elements are found, it returns -1.

// example only contains of findIndex()
// findLastIndex() works the same but will return last element index.
const num = [1,2,3,4,5,8,6,7,9]
console.log(num.findIndex(ele => ele>7))//8 is at index 5
console.log(num.findIndex(ele => ele>10))// no element greater than 10

Array.flat()

This method creates a new array with all the sub-array elements added in order into it recursively up to the specified depth

const num = [1,2,3,4,[5,6,7],8,9]
console.log(num.flat())
const num2 = [1,2,3,4,[5,[[6]],7],8,9]
console.log(num2.flat(2))

Array.flatMap()

This method returns a new array which is formed according to the condition given in the callback function to each element of the array, and then flattens the result by one level.

const num = [1,2,3,4,[5,6,7],8,9]
console.log(num.flatMap((ele) => ele*2))
console.log(num.flatMap((ele) => ele))

Array.forEach()

This is a method for the array which works with each element and applies the function to each element.

const num = [1,2,3,4]
num.forEach(ele => console.log(ele*ele))

Array.includes()

This method checks for a certain value among the entries of the array and returns true if value is found else false

const num = [1,2,3,4]
console.log(num.includes(4))

Array.indexOf() and Array.lastIndexOf()

These two method returns the first and last index of the given element much like Array.findIndex() and Array.findLastIndex() method we saw earlier but unlike previous method, indexOf() allows us to decide which index to start the search from.

array.indexOf(searchElement)

array.indexOf(searchElement, fromIndex)

array.lastIndexOf(searchElement)

array.lastIndexOf(searchElement, fromIndex)

const num = [1,2,3,4,5,6,7,8,9,5,6,4,4,5,4]
console.log(num.indexOf(4,5))
console.log(num.lastIndexOf(4,num.length-2))

As you can see we started from the index 5 which holds the value 6 so we got the first 4 after 6 which was at the last index of 11. And for the lastIndexOf() we got num.length which is 15 and we started with 13th index and going reverse we got 4 at 12th index

Array.join()

This is a method used to join elements of array with a specific separated which is optional. The join() method creates and returns a new String by concatenating all the elements in an array. By default the separator is commas. If array has only one item it will remain unaffected.

arr.join() `arr.join('-')

const name = ['m','a','n','g','o']
console.log(name.join())
console.log(name.join('-'))
console.log(name.join('_'))

Array.map()

The map() method is another of the popular method people use. It creates new array and populates it with the results of calling the function on every element in the array

const numbers = [1,2,3,4,5,6,7]
const squaredNum = numbers.map(ele => ele*ele)
console.log(squaredNum)

Array.pop()

The pop() method removes the last element from an array and returns that element. This changes the original array's length

const numbers = [1,2,3,4,5,6,7]
console.log(`The Length before pop() is : ${numbers.length}`)
const popped = numbers.pop()
console.log(`The removed element : ${popped}`)
console.log(`The Array after Change ${numbers}`)
console.log(`The Length after pop() is : ${numbers.length}`)

Array.push()

The push() method adds one or more elements to end the array and returns the new length of the array

array.push(element1, element2,...,elementN)

const numbers = [1,2,3,4,5]
console.log(`The Length before push() is : ${numbers.length}`)
numbers.push(6,7,8)
console.log(`The Array after Change ${numbers}`)
console.log(`The Length after push() is : ${numbers.length}`)

Array.reduce()

The reduce() method executes a user-supplied "reducer" callback function on every element of the array. It works on each element step by step and in order. It does not change the original array

reduce((previousValue, currentValue, currentIndex, array) => { /* … */ } )

const numbers = [1,2,3,4,5]
console.log(numbers.reduce((ele, sum) => sum + ele))

Array.reverse()

The reverse() method reverse an array and returns the reference to same array, i.e it modifies the original array.

const numbers = [1,2,3,4,5]
console.log(numbers)
numbers.reverse()
console.log(numbers)

Array.shift()

This method removes the first element from the array and returns that element.

const numbers = [1,2,3,4,5,6,7]
console.log(`The Length before shift() is : ${numbers.length}`)
const shifted = numbers.shift()
console.log(`The removed element : ${shifted}`)
console.log(`The Array after Change ${numbers}`)
console.log(`The Length after shift() is : ${numbers.length}`)

Array.unshift()

The unshift() method adds one or more elements to the beginning the array instead at the last like push() and like push() it also changes the length.

const numbers = [1,2,3,4,5]
console.log(`The Length before unshift() is : ${numbers.length}`)
numbers.unshift(6,7,8)
console.log(`The Array after Change: ${numbers}`)
console.log(`The Length after unshift() is : ${numbers.length}`)

Array.slice()

The slice() method returns a copy of the portion of an array into new array object selected from start to end, where start and end are index of the items of the array. This method does not modified the original array

slice() slice(start) slcie(start,end)

const numbers = [1,2,3,4,5,6,7,8]
const sliced = numbers.slice(2,4)
console.log(numbers)
console.log(sliced)

Array.some()

The some() method tests a condition just like every() method but instead of matching the condition to all elements like it did in every(), in some() we just check if some elements match the condition, if some elements match then we return true If no element matches we return false

const isEven = (value) => value%2===0
const arr1 = [2,4,6,8]
const arr2 = [2,4,6,7]
const arr3 = [1,3,5,7]
console.log(arr1.some(isEven))
console.log(arr2.some(isEven))
console.log(arr3.some(isEven))

Array.sort()

This method sorts the array like the name suggests, it can sort both numbers and alphabets. We can also given a sorting condition. The default sorting condition is ascending.

const numbers = [1,2,6,7,8,34,5,21,5,2,1,0,12,45]
const alpha = ['r','t','v','f','a','b']
console.log(numbers.sort((a,b) => a-b))
console.log(alpha.sort())

Array.splice()

This method is used to change chunks of array and resize the array while changing the original array completely. We can delete the items or change their value using splice.

General Syntax

splice(start, deleteCount, item1, item2, itemN)

const numbers = [1,2,3,4,5,6,7]
const numbers1 = [1,2,3,4,5,6,7]
numbers.splice(2,3)
numbers1.splice(2,2,'a','4')
console.log(numbers)
console.log(numbers1)

Flexbox is a 1-D layout method for arranging items in rows or columns. Items expand to fill additional space or shrink to fit into smaller containers. Here we are going to discuss most of the things flexbox offers.

Flexbox offers the same set of things provided by CSS positioning but in a much more straightforward, flexible way. The main thing we keep in mind when using the flexbox is the container and its children.

Let's dive in

FlexBox Properties

This is without the flex property.

 .container{
    gap: 10px;
    display: flex;
}

By default, the flex-direction is row so all the elements inside the container are aligned in a row.

We can also add values to the flex-direction property

.container{
    gap: 10px;
    display: flex;
    flex-direction: column-reverse;
}

flex-direction has 4 property values we can use. What flex-direction does is, it changes the axis according to the property value we assign.

This is an image from MDN docs that gives us a better understanding of the axis. When we used flex-direction: column-reverse the main axis became from bottom-to-top and the direction matters for the upcoming property we will be exploring. The 4 values for flex-direction are given below:

• column: This value places the flex items vertically, from top to bottom.
• column-reverse: This value places the flex items vertically but from bottom to top.
• row: This value places the flex items horizontally, from left to right.
• row-reverse: This value places the flex items horizontally but from right to left

Flex-wrap

This happens when we have too many items clumped up together, to solve this issue we have flex-wrap because by default the flex items try to shrink and stay in the row/column so we need to add additional property to remove that skewed look.

.container{
    gap: 10px;
    display: flex;
    flex-wrap: wrap;
    border: 1px solid red;
}

flex-wrap has 3 property value

• wrap : This will be wrap flex items in multiple lines from top to bottom
• no-wrap : This property doe not affect the row in any manner
• wrap-reverse: This property is similar to row-reverse where it wraps the items but in reverse order that is bottom to top

flex-flow

Now that you have learned about the two properties, lets combine them with flex-flow This property is combination of flex-direction and flex-wrap and the generic syntax would be flex-flow: flex-direction flex-wrap

.container{
  flex-flow: row-reverse wrap
}

justify-content

This is one of the property which is affected by the flex-direction. This property aligns the items along the main axis which is decided by the flex-direction. For simplicity we will be using flex-direction: row.

justify-content: flex-start

justify-content: flex-end

justify-content: space-between

justify-content: space-around

justify-content: space-evenly

align-content

This property displaces the items according to cross-axis. We have taken a flex-direction: row so in the upcoming examples the displacement will occur in y-axis.

align-content: flex-start

align-content: flex-end

align-content: center

align-content: stretch

align-items

This property aligns the flex lines. It defines how the flex items should distribute vertically on the current line. It is for items in a single row. Major difference between align-items and align-content is that `align-content doesn't interfere with items in a row but with rows itself.

• stretch: Flex items are stretched to take up the leftover space.
• flex-start/start/self-start: Flex items are placed at the start of the vertical or cross axis.
• flex-end/end/self-end: Flex items are placed at the end of the vertical or cross axis.
• center: Flex items are placed in the center along with the cross or vertical axis.
• baselines: Flex items are aligned such as their baselines align.

Other Propeties

Order: This property decides the order in which elements are positioned. by default the elements have a order of 0. So, if we want to bring something to front we can assign it a lower value like order:-1 or if we want to push something to the end we can assign it a higher value.

.blacklogo{
order:-1
}

.redlogo{
order: 6
}

In the above examples we pushed the red logo at the last by give it a higher enough value. And brought the black logo in the front by applying it an lower enough value

align-self: It can be used to override the align-items by applying it to an individual element.

Setup and Initialization

This command is used to initialize an existing folder as a git repo

git init

This is used to copy a git repo

git clone [URL]

Stage and Snapshot

Show modified files in the working directory that are staged for your next commit git status

Add a file for your next commit

git add [fileName]

to add all files

git add .

unstaged a file while retaining the changes in the working directory

git reset [fileName]

check the difference between what is changed but not staged

git diff

check the difference between what is staged but not yet committed

git diff --staged

Commit staged content as a new commit snapshot

git commit -m "message"

Branch and Merge

List your branches. A * will appear next to the currently active branch

git branch

Create a new branch at the current commit

git branch [branch-name]

Switch to another branch and check it into your working directory

git checkout

merge the specified branch's history into the current one

git merge [branch]

show all the commits in the current branch's history

git log

Inspect and Compare

show the commits on BranchA that are not in BranchB

git log branchB..branchA

show the commit that changed file, even across renames

git log --follow [file]

show the diff of what is in BranchA that is not in BranchB

git diff branchB..branchA

show any object in Git in human readable format

git show [SHA]

Tracking Path Changes

Delete the files from project and stage the removal for commit

git rm [file]

change an existing file path and stage the move

git mv[existing-path][new-path]

show all commit logs with indication of any paths that moved

git log --state -M

Share and Update

add a git URL as an alias

git remote add [alias][URL]

fetch down all the branches from that git remote

git fetch [alias]

Merge a remote branch into your current branch to bring it up to date

git merge [alias]/[branch]

Transmit local branch commits to the remove repo branch

git push [alias][branch]

fetch and merge any commits from the tracking remote branch

git pull

Rewrite History

apply any commits of current branch ahead of specified one

git rebase [branch]

clear staging area, rewrite working tree from specified commit

git reset --hard[commit]

Temporary Commits

Save modified and staged changes

git stash

list the stack-order of stashed file changes

git stash list

write working from top of stash stack

git stash stop

discard the changes from the top of stash stack

git stash drop

This is pretty much all important git commands. I hope it helped. Thanks and Keep Learning!

Markdown is a plain text formatting syntax that is focused on making writing on the internet easier. It can also be considered as an alternative to WYSIWYG editors. WYSIWYG is What You See Is What You Get... MarkDown files have an extension of .md. If you have worked with Github you must be familiar with it.

It is much easier to learn and fast to use without too many tags mussing everything up.

Basic Syntax

Heading

Just like in HTML heading here ranges from 1-6 with size decreasing. # followed by space and then Heading. # Heading 1

Heading 1

## Heading 2

Heading 2

### Heading 3

Heading 3

Bold

For Bold we use ** or __ on both sides of the text **Bold** __Bold__

Bold Bold

Italic

For Italics, we use * or _

Italic Italic

Blockquote

For blockquote, we use > followed by space

BlockQuote

Ordered List

For Ordered List

1. First item
2. Second item
3. Extra

1. First item
2. Second item
3. Extra

the point here to note is that any number followed by . and space will get ordered serially. Even if we write 9. nth item the list will begin from 1

Unordered List

Unordered List we can use - followed by space

- First item
- Second item
- Third item

• First item
• Second item
• Third item

Code

Code can be written between the backticks

`code`

if we want a block of code we can have 3 such backticks /backquotes, and to highlight the code inside we can mention the language/format it's in right after the first 3 backquotes.

Horizontal Line

A horizontal line can be drawn using --- but must have an empty line above it

Link

Link can be added using

[Youtube](www.Youtube.com)

Youtube

Image

Image Addition can also be done in the same manner but we have to add ! before the entire line.

![SomeName](LinkToImage)

Extended Syntax

Table

To add a table, use three or more --- to create each column's header, and use | to separate each column.

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

StrikeThrough

You can strikethrough words by putting a horizontal line using ~~ before and after the words you want to strike.

TaskLists

Task lists allow you to create a list of items with checkboxes.

- [x] Step one
- [x] Step two
- [ ] Step Three

• [x] Step one
• [x] Step two
• [ ] Step Three

Emoji

Some Markdown supports emoji as well

Gone camping! :tent: Be back soon.

That is so funny! :joy:

Highlighting

Highlighting can be done using == on both sides of important words.

I need to highlight these ==very important words==.

Subscript and SuperScript

For Subscript we use ~ and For Superscript we use ^

H~2~O
X^3^

This is pretty much all the features of Markdown at the time of publishing this article. The features which don't have examples using the md code are not supported by the platform as of now. Thanks for Reading, Keep Learning!

The most annoying part of styling is to position that one div which refuses to obey css commands. It's frustrating and mentally draining BUT why does this happen in the first place? This Article will help you understand the nature of various positions in CSS to prevent such things from happening. There are various types of CSS Positions. We will cover them here.

Position Static

Now this is a very common position, the default position of HTML is static, This position allows a normal flow of the document and displays things as they are ordered in HTML. The top,right,left,bottom, and z-index properties do not affect position: static.

<div class="parent">
    <div class="child1"></div>
    <div class="child2"></div>
    <div class="child3"></div>
</div>

CSS

  .parent{
}
.child1{
}
.child2{
}
.child3{
}

OUTPUT

Position relative

This position stacks on top of the position static as if it contained a z-index and stacks on top of the normal flow of the document. The Offset values of top,right,left and bottom shows it. For example

HTML

<div class="parent">
    <div class="child1"></div>
    <div class="child2"></div>
    <div class="child3"></div>
</div>

CSS

  .parent{
}
.child1{
    position: relative;
    left: 50px;

}
.child2{
}
.child3{
}

OUTPUT

When we add more offset parameters

CSS

  .parent{
}
.child1{
    position: relative;
    left: 50px;
    top: 20px
}
.child2{
}
.child3{
}

OUTPUT

Effect of position: relative on table-row,table-column,table-cell elements is undefined. Also, the relative position of the element does not affect the other elements positioned in the HTML Document

Position Absolute

The absolute position removes the element from the normal flow of the document and is positioned to the closest positioned ancestor, if there is no closest ancestor it will be placedrelative to the page. After which we can assign it the offset values of top,right,bottom,left which will decide its final position

HTML

<div class="parent">
    <div class="child1">There is</div>
    <div class="child2"></div>
    <div class="child3"></div>
</div>

CSS

  .parent{
}
.child1{
    position: absolute;
    left: 100px;
    top: 30px;
}
.child2{
}
.child3{
}

OUTPUT

As you can see the child1 has been aligned according to the page and not according to its parent div. And the behavior of other elements is as if the child1 didn't exist.

Position Fixed

This is very similar to the absolute position as it will also be removed from the flow of the document/page. But fixed will always be relative to the document and is unaffected by scrolling. For example in the above HTML

.parent{
}
.child1{
    position: fixed;
    left: 100px;
    top: 30px;
}
.child2{

}

.child3{

}

OUTPUT

In the sample, you can see that even when scrolling the child1 has maintained its position according to the offset value as it is sticking to the document. It can be used to create floating elements that are always in the viewport

Position Sticky

This is a very unique position, sticky can be considered as a hybrid of the relative and fixed position. Until we reach the end of the viewport it acts as if it were relative and as soon as we cross the threshold of the viewport when scrolling, it starts behaving like a fixed. It requires at least one of the offset values to stick to.

This brings us to the end of our learning journey with CSS Position. Hope the article helped you. Thanks and Keep Learning