Version Compatibility Archives

.cursorrules Convex

This document serves as some special instructions when working with Convex.

# Schemas

When designing the schema please see this page on built in System fields and data types available: https://docs.convex.dev/database/types

Here are some specifics that are often mishandled:

## v (https://docs.convex.dev/api/modules/values#v)

The validator builder.

This builder allows you to build validators for Convex values.

Validators can be used in schema definitions and as input validators for Convex functions.

Type declaration
Name	Type
id	(tableName: TableName) => VId<GenericId, "required">
null	() => VNull
number	() => VFloat64
float64	() => VFloat64
bigint	() => VInt64
int64	() => VInt64
boolean	() => VBoolean
string	() => VString
bytes	() => VBytes
literal	(literal: T) => VLiteral
array	(element: T) => VArray
object	(fields: T) => VObject<Expand<{ [Property in string | number | symbol]?: Exclude<Infer, undefined> } & { [Property in string | number | symbol]: Infer }>, T, "required", { [Property in string | number | symbol]: Property | `${Property & string}.${T[Property]["fieldPaths"]}` }[keyof T] & string>
record	(keys: Key, values: Value) => VRecord<Record<Infer, Value["type"]>, Key, Value, "required", string>
union	(...members: T) => VUnion
any	() => VAny
optional	(value: T) => VOptional

## System fields (https://docs.convex.dev/database/types#system-fields)

Every document in Convex has two automatically-generated system fields:

_id: The document ID of the document.
_creationTime: The time this document was created, in milliseconds since the Unix epoch.

You do not need to add indices as these are added automatically.

## Example Schema

This is an example of a well crafted schema.

```ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema(
  {
    users: defineTable({
      name: v.string(),
    }),
    
    sessions: defineTable({
      userId: v.id("users"),
      sessionId: v.string(),
    }).index("sessionId", ["sessionId"]),
    
    threads: defineTable({
      uuid: v.string(),
      summary: v.optional(v.string()),
      summarizer: v.optional(v.id("_scheduled_functions")),
    }).index("uuid", ["uuid"]),

    messages: defineTable({
      message: v.string(),
      threadId: v.id("threads"),
      author: v.union(
        v.object({
          role: v.literal("system"),
        }),
        v.object({
          role: v.literal("assistant"),
          context: v.array(v.id("messages")),
          model: v.optional(v.string()),
        }),
        v.object({
          role: v.literal("user"),
          userId: v.id("users"),
        }),
      ),
    })
      .index("threadId", ["threadId"]),
  },
);

by @PatrickJS

.cursorrules Code Guidelines

1. **Verify Information**: Always verify information before presenting it. Do not make assumptions or speculate without clear evidence.

2. **File-by-File Changes**: Make changes file by file and give me a chance to spot mistakes.

3. **No Apologies**: Never use apologies.

4. **No Understanding Feedback**: Avoid giving feedback about understanding in comments or documentation.

5. **No Whitespace Suggestions**: Don't suggest whitespace changes.

6. **No Summaries**: Don't summarize changes made.

7. **No Inventions**: Don't invent changes other than what's explicitly requested.

8. **No Unnecessary Confirmations**: Don't ask for confirmation of information already provided in the context.

9. **Preserve Existing Code**: Don't remove unrelated code or functionalities. Pay attention to preserving existing structures.

10. **Single Chunk Edits**: Provide all edits in a single chunk instead of multiple-step instructions or explanations for the same file.

11. **No Implementation Checks**: Don't ask the user to verify implementations that are visible in the provided context.

12. **No Unnecessary Updates**: Don't suggest updates or changes to files when there are no actual modifications needed.

13. **Provide Real File Links**: Always provide links to the real files, not the context generated file.

14. **No Current Implementation**: Don't show or discuss the current implementation unless specifically requested.

15. **Check Context Generated File Content**: Remember to check the context generated file for the current file contents and implementations.

16. **Use Explicit Variable Names**: Prefer descriptive, explicit variable names over short, ambiguous ones to enhance code readability.

17. **Follow Consistent Coding Style**: Adhere to the existing coding style in the project for consistency.

18. **Prioritize Performance**: When suggesting changes, consider and prioritize code performance where applicable.

19. **Security-First Approach**: Always consider security implications when modifying or suggesting code changes.

20. **Test Coverage**: Suggest or include appropriate unit tests for new or modified code.

21. **Error Handling**: Implement robust error handling and logging where necessary.

22. **Modular Design**: Encourage modular design principles to improve code maintainability and reusability.

23. **Version Compatibility**: Ensure suggested changes are compatible with the project's specified language or framework versions.

24. **Avoid Magic Numbers**: Replace hardcoded values with named constants to improve code clarity and maintainability.

25. **Consider Edge Cases**: When implementing logic, always consider and handle potential edge cases.

26. **Use Assertions**: Include assertions wherever possible to validate assumptions and catch potential errors early.

by @Hamza Farhan