Hey Fauna team,
I’m currently in the process of building a TypeScript (TS) wrapper for Fauna’s FQLv10 API, and I wanted to reach out to get some feedback and guidance from the community and possibly the Fauna engineering team.
Background:
Over a year ago, I started using FaunaDB for a future SaaS project. I’ve been building out some backend microservices as part of this long-term project, and FaunaDB became the database of choice due to its powerful features. As part of the journey, I recently began migrating from FQL v4 to FQL v10, and during that migration, I realized the need for a custom wrapper to simplify interaction with the API, especially from a TypeScript perspective.
I’ve invested around 20 hours so far into this side project, which has allowed me to explore Fauna’s API, improve my FQL syntax, and build something functional that aligns with my larger SaaS goals.
What I’m working on:
I’m aiming to create a flexible TypeScript wrapper that helps abstract FQLv10 into easier-to-use constructs. For instance, I’d like to offer helper methods that handle common operations like .getByName() or .getWhere() directly within the wrapper, without requiring manual FQL construction each time. This would enable me (and others) to work with Fauna in a more seamless and TS-friendly way.
Here’s a breakdown of what I’m doing:
- Generating FQL instructions: Building functions that output FQLv10 fragments or full instructions as strings.
- Collection Abstractions: Creating a way to define collections and operations like CRUD in TypeScript while keeping it flexible for additional use cases.
- Manual Testing: I’ve been testing the instructions in the Fauna web app and writing unit tests along the way.
- Class-based Structure: Eventually, I’ll organize this into classes for easier use and extensibility.
- Community Focus: I believe this could be useful for others in the community as well, once it’s more polished.
Use Case Example:
One interesting idea I’ve been working on is defining client-specific schemas and collections. My goal is to lazily create backend artifacts like collections as needed, per client, making it easy to segregate data.
For instance, I’m working on something like this:
class Notifications extends Collection {
constructor(config: ...) {
// Constructor logic here
}
// Define methods like getByName, getWhere, etc.
}
This abstraction would allow me to use TypeScript methods instead of manually constructing FQL queries. Here’s a snippet of the type of code I’m working through:
export function createRole(c: RoleConfig) {
c = checkRoleConfig(c);
return `
if (Role.byName("${c.name}") != null) {
"${c.name} role already exists";
} else {
Role.create({
name: "${c.name}"
${renderPriviledges(c)}
${renderMembership(c)}
${renderData(c)}
});
}
`;
}
My Concerns and Questions:
As an early adopter of FQLv10 and someone who’s still learning the nuances, I’m curious about a few things:
- Fauna’s Roadmap for FQLv10 TS Support: Is Fauna planning to release an official FQLv10 TypeScript wrapper soon? If so, I don’t want to spend too much time duplicating efforts.
- General Feedback: Does this project sound useful or interesting to the wider Fauna community? Would this type of wrapper be something worth open-sourcing, and are there potential opportunities for collaboration with the Fauna team?
- Best Practices: Are there any specific technical considerations or best practices you would recommend for this project? Especially as I’m new to certain aspects of FQL syntax and Fauna’s advanced features.
- Schema Validation: Internally, I’ve been using Zod for schema validation in TS, which has been quite useful for ensuring config object correctness before generating FQL instructions. Is this a good approach, or is there a more Fauna-native way to achieve similar results?
Any feedback, advice, or guidance would be greatly appreciated. I’d love to hear your thoughts on whether this project could be valuable to the community and if collaboration with the Fauna team would make sense.
Thanks for your time and consideration!
