r3ckon-style

Rename or restructure until the code reads. The name holds what the comment would have said, and it cannot go stale.

// grace period is 15 min after publish
if (Date.now() - post.publishedAt < 900_000) {
  ...
}

const EDIT_GRACE_PERIOD_MS = 15 * 60 * 1000

function isWithinEditGracePeriod(post: Post) {
  return Date.now() - post.publishedAt < EDIT_GRACE_PERIOD_MS
}

if (isWithinEditGracePeriod(post)) {
  ...
}

Not in code, string literals, UI copy, prose, or commit messages. A comma, a colon, parentheses, or a full stop.

toast.error("Session expired — sign in again")

toast.error("Session expired. Sign in again.")

Three or more branches on the same discriminant becomes a switch. Drop default on a closed union and TypeScript fails the build when someone adds a case and forgets this file, which is the point.

if (status === "queued") {
  return "Queued"
} else if (status === "running") {
  return "In progress"
} else if (status === "failed") {
  return "Failed"
} else {
  return "Done"
}

switch (status) {
  case "queued":
    return "Queued"
  case "running":
    return "In progress"
  case "failed":
    return "Failed"
  case "done":
    return "Done"
}

Handle the exits first, then write the happy path flat at the bottom. Past two levels inside a function, extract or invert.

if (post) {
  if (post.authorId === user.id) {
    if (post.status === "draft") {
      return publish(post)
    } else {
      throw new ConflictError()
    }
  } else {
    throw new ForbiddenError()
  }
} else {
  throw new NotFoundError()
}

if (!post) throw new NotFoundError()
if (post.authorId !== user.id) throw new ForbiddenError()
if (post.status !== "draft") throw new ConflictError()

return publish(post)

Never call setState inside useEffect. If a value can be computed from props or existing state, compute it during render.

const [fullName, setFullName] = useState("")

useEffect(() => {
  setFullName(`${first} ${last}`)
}, [first, last])

const fullName = `${first} ${last}`

To clear state when an identity changes, remount the subtree with a key. React throws the old state away for you.

useEffect(() => {
  setDraft("")
}, [conversationId])

<MessageComposer key={conversationId} />

Everything goes through cn(), because tailwind-merge cannot resolve a conflict it cannot see inside a template literal.

className={`p-2 ${isActive ? "bg-accent" : ""} ${className}`}

className={cn("p-2", isActive && "bg-accent", className)}

Parse, do not validate. The schema's output type is what the rest of the function sees, so an unparsed value is never in scope. Bodies, query strings, params, webhooks, env vars, third-party responses.

export async function POST(request: Request) {
  const body = await request.json()
  await createInvite(body.email, body.role)
}

const CreateInvite = z.object({
  email: z.string().email("Enter a valid email address"),
  role: z.enum(["admin", "member"]),
})

export async function POST(request: Request) {
  const parsed = CreateInvite.safeParse(await request.json())
  if (!parsed.success) return badRequest(parsed.error)

  await createInvite(parsed.data)
}

Scope the query by the authenticated principal instead of fetching and then checking. It also avoids telling an attacker that a resource exists but is not theirs.

const project = await projects.findOne({
  _id: new ObjectId(id),
})

if (project.ownerId !== session.userId) {
  throw new ForbiddenError()
}

const project = await projects.findOne({
  _id: new ObjectId(id),
  ownerId: session.userId,
})

if (!project) throw new NotFoundError()

Database documents grow fields. A handler that spreads one into a response leaks whatever someone adds next year. One mapper per resource, _id to a string id, dates to ISO.

return Response.json(user)

return Response.json({
  ...user,
  passwordHash: undefined,
})

function toPublicUser(user: UserDocument) {
  return {
    id: user._id.toString(),
    email: user.email,
    role: user.role,
  }
}

Imperative, lowercase, no trailing period, under 72 characters. Optimize for git log --oneline and blame, not for the GitHub commit page. Say what changed, not that something changed.

feat: Added a new endpoint for revoking sessions.
feat: adds session revocation endpoint
feat: session revocation

feat(auth): add session revocation endpoint

type/ticket-description. Lowercase, hyphenated, three to five words. Ticket ids keep their upstream casing. Without a tracker, drop the segment rather than inventing a number.

Feature/AddLoginPage
feature/add_login_page
gautam-working-branch

feature/PROJ-123-add-login-page
fix/PROJ-88-session-expiry-rounding
hotfix/revoke-leaked-api-keys