@evolu/common 2.0.0 → 2.0.2

package/README.md

@@ -1,156 +1,33 @@
 # Evolu
 
-[Local-first](https://www.inkandswitch.com/local-first/) platform designed for privacy, ease of use, and no vendor lock-in to sync&back precious data.
-
-- [SQLite](https://sqlite.org/) in all browsers, Electron, and React Native
-- E2E encrypted sync and backup with [CRDT](https://crdt.tech/) (merging changes without conflicts)
-- Free Evolu server for testing (paid production-ready soon, or you can run your own)
-- Typed database schema with branded types (`NonEmptyString1000`, `PositiveInt`, etc.)
-- Reactive queries with React Suspense support
+[Local-first](https://www.inkandswitch.com/local-first) platform designed for privacy, ease of use, and no vendor lock-in
+
+- [SQLite](https://sqlite.org) in all browsers, Electron, and React Native
+- [CRDT](https://crdt.tech) for merging changes without conflicts
+- End-to-end encrypted sync and backup
+- Free Evolu sync and backup server, or you can run your own
+- Typed database schema (with branded types like `NonEmptyString1000`, `PositiveInt`, etc.)
+- Typed SQL via [Kysely](https://kysely.dev)
+- Reactive queries with full React Suspense support
 - Real-time experience via revalidation on focus and network recovery
-- Schema evolving via `filterMap` ad-hoc migration
-- No signup/login, no email collection, only Bitcoin-like mnemonic (12 words)
-- Fetching nested objects and arrays in a single SQL query
-- JSON support with automatic parsing and stringifying
+- No signup/login, only bitcoin-like mnemonic (12 words)
+- Ad-hoc migration
+- Sqlite JSON support with automatic stringifying and parsing
+- Support for [Kysely Relations](https://kysely.dev/docs/recipes/relations) (loading nested objects and arrays in a single SQL query)
+- Local-only tables (tables with \_ prefix are not synced)
+- Evolu Solid/Vue/Svelte soon
 
 ## Local-first apps
 
-Local-first apps allow users to own their data. Evolu stores data in the user's device(s), so Evolu apps can work offline and without a specific server. How is it different from keeping files on disk? Files are not the right abstraction for apps and are complicated to synchronize among devices. That's why client-server architecture rules the world. But as with everything, it has trade-offs.
-
-### The trade-offs of the client-server architecture
-
-Client-server architecture provides us with easy backup and synchronization, but all that depends on the ability of a server to fulfill its promises. Internet is offline, companies go bankrupt, users are banned, and errors occur. All those things happen all the time, and then what? Right, that's why the world needs local-first apps. But until now, writing local-first apps has been challenging because of the lack of libraries and design patterns. That's why I created Evolu.
-
-## Overview
-
-### Define Data
-
-To start using Evolu, define tables for your database and export React Hooks.
-
-```ts
-import * as S from "@effect/schema/Schema";
-import * as Evolu from "@evolu/react";
-
-const TodoId = Evolu.id("Todo");
-type TodoId = S.Schema.To<typeof TodoId>;
-
-const TodoTable = S.struct({
-  id: TodoId,
-  title: Evolu.NonEmptyString1000,
-  isCompleted: Evolu.SqliteBoolean,
-});
-type TodoTable = S.Schema.To<typeof TodoTable>;
-
-const Database = S.struct({
-  todo: TodoTable,
-});
-
-export const {
-  useQuery,
-  useMutation,
-  useOwner,
-  useOwnerActions,
-  useEvoluError,
-} = Evolu.create(Database);
-```
-
-### Validate Data
-
-Learn more about [Schema](https://github.com/effect-ts/schema).
-
-```ts
-import * as S from "@effect/schema/Schema";
-import * as Evolu from "@evolu/react";
-
-S.parse(Evolu.String1000)(title);
-```
-
-### Mutate Data
-
-Mutation API is designed for local-first apps to ensure changes are always merged without conflicts.
-
-```ts
-const { create, update } = useMutation();
-
-create("todo", { title, isCompleted: false });
-update("todo", { id, isCompleted: true });
-```
-
-### Query Data
-
-Evolu uses type-safe TypeScript SQL query builder [kysely](https://github.com/koskimas/kysely), so autocompletion works out-of-the-box.
-
-```ts
-const { rows } = useQuery(
-  (db) => db.selectFrom("todo").select(["id", "title"]).orderBy("updatedAt"),
-  // (row) => row
-  ({ title, ...rest }) => title && { title, ...rest },
-);
-```
-
-### Protect Data
-
-Evolu encrypts data with Mnemonic, a safe autogenerated password based on [bip39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki).
-
-```ts
-const owner = useOwner();
-
-alert(owner.mnemonic);
-```
-
-### Delete Data
-
-Leave no traces on a device.
-
-```ts
-const ownerActions = useOwnerActions();
-
-if (confirm("Are you sure? It will delete all your local data."))
-  ownerActions.reset();
-```
-
-### Restore Data
-
-Restore data elsewhere. Encrypted data can only be restored with a Mnemonic.
-
-```ts
-const ownerActions = useOwnerActions();
-
-ownerActions.restore(mnemonic).then((either) => {
-  if (either._tag === "Left") alert(JSON.stringify(either.left, null, 2));
-});
-```
-
-### Handle Errors
-
-Evolu `useQuery` and `useMutation` never fail, it's the advantage of local first apps, but Evolu, in rare cases, can.
-
-```ts
-const evoluError = useEvoluError();
-
-useEffect(() => {
-  // eslint-disable-next-line no-console
-  if (evoluError) console.log(evoluError);
-}, [evoluError]);
-```
-
-And that's all. Minimal API is the key to a great developer experience.
-
-## Privacy
-
-Evolu uses end-to-end encryption and generates strong and safe passwords for you. Evolu sync and backup server see only userId and timestamps.
-
-## Trade-offs
-
-> “There are no solutions. There are only trade-offs.” ― Thomas Sowell
+Local-first apps allow users to own their data by storing them on their devices. Modern browsers provide API designed precisely for that. How is it different from keeping files on disk? Files are not the right abstraction for apps and cannot synchronize among devices. That's why traditional apps use the client-server architecture. But using client-server architecture also means that users' ability to use an app depends on some server that can be offline, temporarily or forever, if a company decides to ban a user or even goes bankrupt. That's unfortunate. Luckily, a way to restore data ownership exists. It's Evolu.
 
-Evolu is not P2P. For reliable syncing and backup, there needs to be a server. Evolu server is very minimal, and everyone can run their own. While it's theoretically possible to have P2P Evolu, I have yet to see a reliable solution. It's not only a technical problem; it's an economic problem. Someone has to be paid to keep your data safe. Evolu provides a free server for testing. Soon we will provide a paid server for production usage.
+## Documentation
 
-All table columns except for ID are nullable by default. It's not a bug; it's a feature. Local-first data are meant to last forever, but schemas evolve. This design decision was inspired by GraphQL [nullability](https://graphql.org/learn/best-practices/#nullability) and [versioning](https://graphql.org/learn/best-practices/#versioning). Evolu provides a handy `filterMap` helper for queries.
+For detailed information and usage examples, please visit [evolu.dev](https://www.evolu.dev).
 
 ## Community
 
-The Evolu community is on GitHub Discussions, where you can ask questions and voice ideas.
+The Evolu community is on [GitHub Discussions](https://github.com/evoluhq/evolu/discussions), where you can ask questions and voice ideas.
 
 To chat with other community members, you can join the [Evolu Discord](https://discord.gg/2J8yyyyxtZ).
 

package/dist/src/Platform.d.ts

@@ -32,10 +32,7 @@ export interface AppState {
     readonly reset: Effect.Effect<never, never, void>;
 }
 export declare const AppState: Context.Tag<AppState, AppState>;
-/**
- * To detect whether DOM can be used.
- * https://github.com/facebook/fbjs/blob/main/packages/fbjs/src/core/ExecutionEnvironment.js
- */
+/** To detect whether DOM can be used. */
 export declare const canUseDom: boolean;
 export {};
 //# sourceMappingURL=Platform.d.ts.map

package/dist/src/Platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../src/Platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAEhD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,eAAe,GACf,kBAAkB,GAClB,cAAc,CAAC;AAEnB,eAAO,MAAM,YAAY,yCAA8B,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEvD,eAAO,MAAM,SAAS,mCAA2B,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAEvD,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACrD;AAED,eAAO,MAAM,QAAQ,iCAA0B,CAAC;AAEhD,MAAM,MAAM,KAAK,GAAG,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,KACb,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AAEhD,eAAO,MAAM,KAAK,2BAAuB,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;CAC7B;AAED,eAAO,MAAM,SAAS,kCAgBrB,CAAC;AAEF,UAAU,cAAc;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,QAAQ,iCAA0B,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,SAAS,SAIrB,CAAC"}
+{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../src/Platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAEhD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,eAAe,GACf,kBAAkB,GAClB,cAAc,CAAC;AAEnB,eAAO,MAAM,YAAY,yCAA8B,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEvD,eAAO,MAAM,SAAS,mCAA2B,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAEvD,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACrD;AAED,eAAO,MAAM,QAAQ,iCAA0B,CAAC;AAEhD,MAAM,MAAM,KAAK,GAAG,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,KACb,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AAEhD,eAAO,MAAM,KAAK,2BAAuB,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;CAC7B;AAED,eAAO,MAAM,SAAS,kCAgBrB,CAAC;AAEF,UAAU,cAAc;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,QAAQ,iCAA0B,CAAC;AAEhD,yCAAyC;AACzC,eAAO,MAAM,SAAS,SAYlB,CAAC"}

package/dist/src/Platform.js

@@ -15,10 +15,16 @@ export const FetchLive = Layer.succeed(Fetch, Fetch.of((url, body) => Effect.try
     catch: () => ({ _tag: "FetchError" }),
 })));
 export const AppState = Context.Tag();
-/**
- * To detect whether DOM can be used.
- * https://github.com/facebook/fbjs/blob/main/packages/fbjs/src/core/ExecutionEnvironment.js
- */
-export const canUseDom = !!(typeof window !== "undefined" &&
-    window.document &&
-    window.document.createElement);
+/** To detect whether DOM can be used. */
+export const canUseDom = (() => {
+    // IDK why try-catch is necessary, but it is.
+    // "ReferenceError: window is not defined" should not happen, but it does.
+    try {
+        return !!(typeof window !== "undefined" &&
+            window.document &&
+            window.document.createElement);
+    }
+    catch (e) {
+        return false;
+    }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Local-first platform designed for privacy, ease of use, and no vendor lock-in to sync and backup people's lifetime data",
   "keywords": [
     "evolu",

package/src/Platform.ts

@@ -70,12 +70,17 @@ export interface AppState {
 
 export const AppState = Context.Tag<AppState>();
 
-/**
- * To detect whether DOM can be used.
- * https://github.com/facebook/fbjs/blob/main/packages/fbjs/src/core/ExecutionEnvironment.js
- */
-export const canUseDom = !!(
-  typeof window !== "undefined" &&
-  window.document &&
-  window.document.createElement
-);
+/** To detect whether DOM can be used. */
+export const canUseDom = ((): boolean => {
+  // IDK why try-catch is necessary, but it is.
+  // "ReferenceError: window is not defined" should not happen, but it does.
+  try {
+    return !!(
+      typeof window !== "undefined" &&
+      window.document &&
+      window.document.createElement
+    );
+  } catch (e) {
+    return false;
+  }
+})();