Support for popular frontend libraries

[maradotwebp]

BlinkDB is 100% frontend framework & library agnostic, and can be used with just about any other frontend technology you can imagine. Nevertheless, there are some features that could be benefitial to most frameworks. I'm planning to create auxiliary packages for React, Vue, Svelte & Solid that wrap most methods in a way more accessible to their respective frontend library.

💡 If you want to support BlinkDB with some code, now would be the perfect opportunity to integrate BlinkDB into your favourite frontend framework :D

In this discussion, I'm going to lay out the plans for the frontend integration for React which I'm going to implement in the near future, but most of the following points apply to every framework that has some idea of hooks/contexts/etc. If you're planning on writing your own package, of course you're not required to follow everything here to the letter, since every framework has its ins and outs which all require different code structures.

---

The auxiliary package for React will be named @blinkdb/react, and will have blinkdb as a peer dependency.

The general aim of the package is to provide hooks for all database retrieval methods, and to create a context provider for DBs & tables.

Context providers

For React, createDB() and createTable() should have their own context.
Tables should be retrievable by context using a custom useTable() hook (which just wraps useContext):

import { useTable } from '@blinkdb/react';
import { DB } from './db.ts';

export const Component = () => {
  const userTable = useTable<DB>('users');
  ...
}

Hooks for database retrieval

In React, a component that needs to fetch data using "vanilla" BlinkDB might look like this:

import { useState, useEffect } from 'react';
import { watch } from 'blinkdb';
import { useTable } from '@blinkdb/react';
import { DB } from './db.ts';

export const ComponentThatFetchesUsers = () => {
  const userTable = useTable<DB>('users');
  const [users, setUsers] = useState([]);
  
  useEffect(async () => {
    const stop = await watch(
      userTable,
      { where: { name: "Alice" } },
      (u) => setUsers(u)
    );
    return () => stop();
  }, []);
  
  ...
}

This logic should be factored out into a custom hook useMany hook that accepts a table & a query and returns the retrieved items:

import { useTable, useMany } from '@blinkdb/react';
import { DB } from './db.ts';

export const ComponentThatFetchesUsers = () => {
  const userTable = useTable<DB>('users');
  const { items } = useMany(userTable, { where: { name: "Alice" } });
  
  ...
}

It will also be benefitial to return properties like isLoading or error similar to other data fetching libraries like https://tanstack.com/query/latest or https://swr.vercel.app/.

Next to the useMany() hook, a useFirst(), useOne() and useCount() hook will also be required.

Database-modifying methods

BlinkDB methods that modify the database in some way (insert(), upsert(),, updateWhere(), etc.) need not be wrapped by the @blinkdb/react package. These methods will most commonly only be used in event handlers anyway.

---

Have any objections, better/more performant designs, or ideas for implementations other frontend frameworks? Leave a reply! I'll periodically update this post with information while I'm working on the React package.

[llamadeus]

Here are a few quick thoughts to kick off the discussion.

1. Using context providers seems like a legit way to me, in order to pass the database or table references to deeper components. Have I understood you correctly, that you want to add individual contexts for the database and each table? If yes, what were your considerations behind this decision?
2. For the hooks for data retrieval, I like the idea of adapting to other libraries' APIs, e.g. having a isLoading or error field. But then, I'd suggest also adapting to returning a data property, instead of items. This would make the return type more consistent among retrieval hooks. Then, for the different hooks useMany(), useFirst(), useOne() and useCount(), the data property can be of a generic type T and each of the hooks return an array of records, one record or a number for data.
3. For database-mutating functions, it would also be possible to add hooks for that and somehow adapt to how Apollo's GraphQL client library implements this. One benefit would be, that it's not required to useDB() then to get the database instance within a component, which would be necessary, if mutating functions remain as they are and do not get dedicated hooks. However, it is questionable, in which ways this complexity is really necessary right now, as your proposal also seems okay to me and would only require one extra line of code.

This may be a topic for another discussion, but am I right assuming that you want to keep the procedural programming style for this library? I'm not trying to convince you of something else. I just want to understand your considerations and implementation goals a little better.

[maradotwebp]

1. If you take a look at the current code, this is currently implemented using two contexts, but one provider component - The context is never exposed directly and only used internally by useTable(), useDB() and BlinkDbProvider. (Within the package, it doesn't matter if there's one or two contexts, the usage is the same to the end user, and two contexts have afaik neither advantages nor disadvantages compared to one context.)
2. That makes complete sense :D Ty, I'll implement it that way.
3. Why would you need the database instance to use mutating functions? They just require a table.
   As an example:

import { uuid, insert } from 'blinkdb';
import { useTable } from '@blinkdb/react';
import { Model } from './model.ts';

export const Component = () => {
  const userTable = useTable((model: Model) => model.users);
  
  const onButtonClick = async () => {
    await insert(userTable, { id: uuid(), name: 'Alice' });
  };
  
  return <button onClick={onButtonClick}>Button</button>;
};

[maradotwebp]

This may be a topic for another discussion, but am I right assuming that you want to keep the procedural programming style for this library?

I assume you mean why the style is insert(userTable, { ... }) instead of userTable.insert({ ... })?

I'm going to stick with that model. Mostly because:

• Code Splitting is available with functions
  • You could theoretically import methods with import { insertMany } from 'blinkdb/core/insertMany' if you're very concerned with code size.
• It makes user-defined functions look more natural
  • If you define a custom method for persisting a table to disk, your custom method saveToDisk(userTable, ...) will then have the same style as the "official" blinkDB methods.

[maradotwebp]

I've since started work on the React client. You can view progress here.

---

While iterating on ideas, I changed the retrieval of tables from the model to this:

const model = (db) => ({
  users: createTable<User>(db, "users")(),
  nested: {
    table: createTable<Post>(db, "posts")()
  }
}) satisfies ValidModel;

type Model = ModelOf<typeof model>;

const Component = () => {
  const userTable = useTable((model: Model) => model.users);
  const postTable = useTable((model: Model) => model.nested.table);
  ...
}

As far as I can tell, this provides no disadvantages compared to the string-based retrieval method as detailed above (useTable<Model>('users')) apart from being slightly more complicated, but allows users to nest and organize tables better.

I may change it back before fully releasing the React client, I'm not too sold on the idea yet.

[maradotwebp]

Current status: React library implemented, available under @blinkdb/react, not published yet.

I'm currently adding the ability to switch between types of API references for the website. This allows users to view different reference pages depending on their needs. For example, the API for exports from @blinkdb/react is only displayed if the user selects "React" in a dropdown on the reference page.

In the future, this should make it easier to add docs for other frontend libraries (Svelte, Vue, ...) while still having a readable reference documentation.

[maradotwebp]

I released the React package a few days ago! 🚀 See v0.13.0.
Continuing with the Vue package, then Solid.

Since the doc rewrite is done now, this should now be less work.

[maradotwebp]

Starting work on the Vue plugin, which is gonna be my final frontend package before the v1.0.0 release.