ReturnDesk Puts the Rules in Postgres
No ORM, no TypeScript, no tests. A one-file schema and a database trigger enforce the return lifecycle while the API stays a thin skin.
- ReturnDesk enforces its entire return lifecycle inside a Postgres trigger, so the API relays decisions the database has already made.
- Every convenience it declined (no ORM, no TypeScript, no tests) is paired with a matching constraint elsewhere that makes the omission safe.
- The API is a validation layer and nothing more; the authority on what a return can do next lives one level below it.
- Its niche is code ownership, which is also its cost: you run and read the whole system, and you also own every gap in it.
A Return Is a Token That Can Only Move Forward
A return in ReturnDesk is a token. It starts as Open, moves to In Review, and then goes to Approved or Rejected. Approved returns carry a resolution (Refund, Replacement, or Store Credit) and eventually reach Completed. Those are the only legal moves.
The surprising part is who decides what is legal. It is not the Express route, and it is not a service method full of if checks. It is a trigger inside schema.sql. The database refuses an illegal transition before the application ever sees an error. The API's job is to ask nicely and relay the answer.
This is a small idea with a large consequence. When the rule lives in the schema, you cannot bypass it by adding a second client, a script, or a background job. Any code that touches the table plays by the same rules, because the rules are part of the table.
The Trigger Is the Guardrail
The trigger fires on updates to the requests table, compares the old status to the new one, and raises an exception if the pair is not an allowed edge in the lifecycle graph. The Express handler in routes/requests.js does not duplicate that logic. It validates the input shape, calls the service, and shapes the response.
The same philosophy shows up twice more. Notes are append-only, so the history of a request cannot be quietly rewritten. Deletions are soft, guarded by a check that the request is still removable, so a closed record stays put. In all three cases the protection sits at the storage layer, not in the app.
Twenty-Four Hours and a One-File Schema
ReturnDesk reads like a take-home exercise that quietly outgrew its brief. The README notes the build took roughly a day, and that the brief only allowed a separate backend service. The author built one anyway, then gave it a real lifecycle and a real guard.
The whole migration story is one file. schema.sql is idempotent, so running it again is safe, and migrate.js executes it as a single multi-statement query. There is no migration framework, no versioned history, and no second source of truth about what the database looks like. You read the schema, and you know the system.
The repository is one contributor and fourteen commits. Stars and forks are at zero. None of that changes what the code argues, but it does tell you who is on the hook if something breaks.
Every Shortcut Was Chosen in Pairs
There is no ORM. All SQL is hand-written inside requestService.js, which is where the business rules and the queries live together. That is a real cost in verbosity and a real gain in transparency. You can read exactly what hits the database.
Two type parsers in db.js are the clearest example of how the constraints were chosen together, not one at a time.
pg.types.setTypeParser(20, (v) => parseInt(v, 10)); // INT8 -> JS number
pg.types.setTypeParser(1700, (v) => parseFloat(v)); // NUMERIC -> JS float
Parsing a Postgres BIGINT into a JavaScript number is usually a mistake, because BIGINT can exceed the safe integer range. Here it is safe for a specific reason: the route layer caps IDs at fifteen digits with /^\d{1,15}$/. Fifteen digits tops out below Number.MAX_SAFE_INTEGER. The parser and the validator were built to fit each other.
The second parser turns a NUMERIC(10,2) refund into a float. That is a genuine precision tradeoff, and the code pays for it on input by rounding with Math.round(refundAmount * 100) / 100 before the value is written. The refund is precise in the database and approximate in memory, and the rounding is what keeps those two facts from disagreeing.
The transaction helper is the other reusable primitive. It checks out a client, begins, runs the callback, commits, rolls back on error, and always releases. One edge case: if the rollback itself throws, that error replaces the original one.
async function withTransaction(fn) {
const client = await pool.connect();
try {
await client.query("BEGIN");
const result = await fn(client);
await client.query("COMMIT");
return result;
} catch (err) {
await client.query("ROLLBACK");
throw err;
} finally {
client.release();
}
}
The routes have no try/catch blocks, and that is deliberate too. Express 5 forwards rejected promises from async handlers straight to the error middleware. The framework change removed the boilerplate, so the boilerplate is gone.
Code You Own vs. Platforms You Rent
The right axis for comparing ReturnDesk is not features. It is deployment and control: whether you install code you can read, rent a hosted service, or bolt a plugin onto someone else's platform.
| Product | Deployment & control | Where the rules live | Customization | Who operates it |
|---|---|---|---|---|
| ReturnDesk (this repo) | Self-hosted JavaScript you run yourself | A Postgres trigger and one schema file | Edit the source directly | Your team |
| WooCommerce returns plugin | Installed inside a commerce platform | Plugin code and platform hooks | Plugin settings and hooks | Merchant, inside WordPress |
| Loop Returns | Hosted SaaS | Vendor's servers, not visible | Configuration and integrations | Vendor plus merchant |
| ReturnGO | Hosted SaaS | Vendor's servers, not visible | Configuration and integrations | Vendor plus merchant |
| AfterShip Returns | Hosted SaaS | Vendor's servers, not visible | Configuration and integrations | Vendor plus merchant |
That table is category-level, not a verified feature comparison. The hosted and plugin rows describe whole product categories, not confirmed competitors of this repository, and none of them were verified against ReturnDesk's actual code. The point is the shape of the trade: renting a returns platform buys you integrations and support; owning the code buys you the ability to read and change the rules, and the obligation to run them.
What It Honestly Does Not Do
The minimalism has a bill, and the code is candid about it. These are the costs of the choices above, not a takedown.
- TLS encryption is on, but the server certificate is not verified (
rejectUnauthorized: false), which leaves the connection open to interception. - Refunds are precise in Postgres and floats in JavaScript. The rounding keeps them honest in practice, not in theory.
- There are no tests. The trigger is the strongest guarantee in the system, and nothing exercises it automatically.
- No TypeScript, so the schema, the validators, and the service layer agree by convention rather than by compiler.
- One maintainer, fourteen commits, zero stars. Bus factor is one.
Read together, these are the same trade stated twice. ReturnDesk spends its safety budget in one place, the database, and accepts thin margins everywhere else. It is a coherent argument that a small, honest system can be assembled from primitives, and that the lifecycle belongs in the schema. Whether you would ship it is a separate question from whether the argument holds.





