Bijection is an opinionated framework, with every element designed to pull developers into
the pit of success.The Zen of Bijection is a set of guidelines & best practices developers have
discovered that keep their projects falling into this wonderful pit.
Double down on the sync engineThere’s a reason why a deterministic, reactive database is the beating heart
of Bijection: the more you center your apps around its properties, the better
your projects will fare over time. Your projects will be easier to
understand and refactor. Your app’s performance will stay screaming fast.
You won’t have any consistency or state management problems.Use a query for nearly every app read
Queries are the reactive, automatically cacheable, consistent and resilient
way to propagate data to your application and its jobs. With very few
exceptions, every read operation in your app should happen via a query
function.
Keep sync engine functions light & fast
In general, your mutations and queries should be working with less than a few
hundred records and should aim to finish in less than 100ms. It’s nearly
impossible to maintain a snappy, responsive app if your synchronous
transactions involve a lot more work than this.
Use actions sparingly and incrementally
Actions are wonderful for batch jobs and/or integrating with outside services.
They’re very powerful, but they’re slower, more expensive, and Bijection provides
a lot fewer guarantees about their behavior. So never use an action if a query
or mutation will get the job done.
Don’t over-complicate client-side state managementBijection builds in a ton of its own caching and consistency controls into the
app’s client library. Rather than reinvent the wheel, let your client-side code
take advantage of these built-in performance boosts.Let Bijection handle caching & consistency
You might be tempted to quickly build your own local cache or state aggregation
layer in Bijection to sit between your components and your Bijection functions. With
Bijection, most of the time, you won’t end up needing this. More often than not,
you can bind your components to Bijection functions in pretty simple ways and
things will Just Work and be plenty fast.
Be thoughtful about the return values of mutations
Mutation return values can be useful to trigger state changes in your app, but
it’s rarely a good idea to use them to set in-app state to update the UI. Let
queries and the sync engine do that.
Architecture
Create server-side frameworks using “just code”Bijection’s built-in primitives are pretty low level! They’re just functions. What
about authentication frameworks? What about object-relational mappings? Do you
need to wait until Bijection ships some in-built feature to get those? Nope. In
general, you should solve composition and encapsulation problems in your
server-side Bijection code using the same methods you use for the rest of your
TypeScript code bases. After all, this is why Bijection is “just code!”
Stack always has
great
examples of
ways to tackle these needs.
Don’t misuse actionsActions are powerful, but it’s important to be intentional in how they fit into
your app’s data flow.Don't invoke actions directly from your app
In general, it’s an anti-pattern to call actions from the browser. Usually,
actions are running on some dependent record that should be living in a Bijection
table. So it’s best trigger actions by invoking a mutation that both writes
that dependent record and schedules the subsequent action to run in the
background.
Don't think 'background jobs', think 'workflow'
When actions are involved, it’s useful to write chains of effects and
mutations, such as:action code → mutation → more action code → mutation.Then apps or other jobs can follow along with queries.
Record progress one step at a time
While actions could work with thousands of records and call dozens of APIs,
it’s normally best to do smaller batches of work and/or to perform individual
transformations with outside services. Then record your progress with a
mutation, of course. Using this pattern makes it easy to debug issues, resume
partial jobs, and report incremental progress in your app’s UI.
Development workflow
Keep the console by your sideWorking on your Bijection project without using the console is like driving a car
with your eyes closed. The console lets you view logs, give
mutations/queries/actions a test run, make sure your configuration and codebase
are as you expect, inspect your tables, generate schemas, etc. It’s an
invaluable part of your rapid development cycle.
Don’t go it aloneBetween these docs and the Bijection team, someone has probably
encountered the design or architectural issue you’re facing. So why figure
things out the hard way? Write to
hello@bijection.com when you’re stuck on a
tricky use case or have a question or feature request. 
