Skip to content

Commit

Permalink
Modernized README
Browse files Browse the repository at this point in the history
  • Loading branch information
@dfahlander
dfahlander committed May 24, 2024
1 parent c6f82b2 commit 28b22e2
Showing 1 changed file with 157 additions and 123 deletions.
280 changes: 157 additions & 123 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,93 +1,164 @@
Dexie.js
========
# Dexie.js

[![NPM Version][npm-image]][npm-url] ![Build Status](https://github.com/dexie/Dexie.js/actions/workflows/main.yml/badge.svg)

Dexie.js is a wrapper library for indexedDB - the standard database in the browser. https://dexie.org
Dexie.js is a wrapper library for indexedDB - the standard database in the browser. https://dexie.org.

#### Why?
Dexie solves three main issues with the native IndexedDB API:
#### Why Dexie.js?

1. Ambiguous error handling
2. Poor queries
3. Code complexity
IndexedDB is the portable database for all browser engines. Dexie.js makes it fun and easy to work with.

Dexie provides a neat database API with a well thought-through API design, robust error handling, extendability, change tracking awareness and extended KeyRange support (case insensitive search, set matches and OR operations).
But also:

* Dexie.js is widely used by 100,000 of web sites, apps and other projects and supports all browsers, Electron for Desktop apps, Capacitor for iOS / Android apps and of course pure PWAs.
* Dexie.js works around bugs in the IndexedDB implementations, giving a more stable user experience.
* It's an easy step to [make it sync](https://dexie.org/#sync).

#### Hello World

```html
<!doctype html>
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/dexie@latest/dist/dexie.js"></script>
<script>
//
// Declare Database
//
var db = new Dexie("FriendDatabase");
db.version(1).stores({
friends: "++id,name,age"
});
//
// Manipulate and Query Database
//
db.friends.add({name: "Josephine", age: 21}).then(function() {
return db.friends.where("age").below(25).toArray();
}).then(function (youngFriends) {
alert ("My young friends: " + JSON.stringify(youngFriends));
}).catch(function (e) {
alert ("Error: " + (e.stack || e));
});
</script>
</head>
<head>
<script src="https://unpkg.com/dexie/dist/dexie.js"></script>
<script>
//
// Declare Database
//
const db = new Dexie('FriendDatabase');
db.version(1).stores({
friends: '++id, age'
});
//
// Play with it
//
db.friends.add({ name: 'Alice', age: 21 }).then(() => {
return db.friends
.where('age')
.below(30)
.toArray();
}).then(youngFriends => {
alert (`My young friends: ${JSON.stringify(youngFriends)}`);
}).catch (e => {
alert(`Oops: ${e}`);
});
</script>
</head>
</html>
```
Yes, it's that simple.

An equivalent modern version (works in all modern browsers):
Yes, it's that simple. Read [the docs](https://dexie.org/docs/) to get into the details.

#### Hello World (for modern browsers)

All modern browsers support ES modules and top-level awaits. No transipler needed. Here's the previous example in a modern flavour:

```html
<!doctype html>
<!DOCTYPE html>
<html>
<head>
<script type="module">
import Dexie from "https://unpkg.com/dexie@latest/dist/modern/dexie.mjs";
//
// Declare Database
//
const db = new Dexie("FriendDatabase");
db.version(1).stores({
friends: "++id,name,age"
});
//
// Manipulate and Query Database
//
try {
await db.friends.add({name: "Josephine", age: 21});
const youngFriends = await db.friends.where("age").below(25).toArray();
alert (`My young friends: ${JSON.stringify(youngFriends)}`);
} catch (e) {
alert (`Error: ${e}`);
}
</script>
</head>
<head>
<script type="module">
// Import Dexie
import { Dexie } from 'https://unpkg.com/dexie/dist/modern/dexie.mjs';
//
// Declare Database
//
const db = new Dexie('FriendDatabase');
db.version(1).stores({
friends: '++id, age'
});
//
// Play with it
//
try {
await db.friends.add({ name: 'Alice', age: 21 });
const youngFriends = await db.friends
.where('age')
.below(30)
.toArray();
alert(`My young friends: ${JSON.stringify(youngFriends)}`);
} catch (e) {
alert(`Oops: ${e}`);
}
</script>
</head>
</html>
```

[Tutorial](https://dexie.org/docs/Tutorial)
#### Hello World (React + Typescript)

Real-world apps are often built using components in various frameworks. Here's a version of Hello World written for React and Typescript. There are also links below this sample to more tutorials for different frameworks...

```tsx
import React from 'react';
import { Dexie, type EntityTable } from 'dexie';
import { useLiveQuery } from 'dexie-react-hooks';

// Typing for your entities (hint is to move this to its own module)
export interface Friend {
id: number;
name: string;
age: number;
}

// Database declaration (move this to its own module also)
export const db = new Dexie('FriendDatabase') as Dexie & {
friends: EntityTable<Friend, 'id'>;
};
db.version(1).stores({
friends: '++id, age',
});

// Component:
export function MyDexieReactComponent() {
const youngFriends = useLiveQuery(() =>
db.friends
.where('age')
.below(30)
.toArray()
);

return (
<>
<h3>My young friends</h3>
<ul>
{youngFriends?.map((f) => (
<li key={f.id}>
Name: {f.name}, Age: {f.age}
</li>
))}
</ul>
<button
onClick={() => {
db.friends.add({ name: 'Alice', age: 21 });
}}
>
Add another friend
</button>
</>
);
}
```

[Tutorials for React, Svelte, Vue, Angular and vanilla JS](https://dexie.org/docs/Tutorial/Getting-started)

[API Reference](https://dexie.org/docs/API-Reference)

[Samples](https://dexie.org/docs/Samples)

### Performance

Dexie has kick-ass performance. Its [bulk methods](https://dexie.org/docs/Table/Table.bulkPut()) take advantage of a lesser-known feature in IndexedDB that makes it possible to store stuff without listening to every onsuccess event. This speeds up the performance to a maximum.
Dexie has kick-ass performance. Its [bulk methods](<https://dexie.org/docs/Table/Table.bulkPut()>) take advantage of a lesser-known feature in IndexedDB that makes it possible to store stuff without listening to every onsuccess event. This speeds up the performance to a maximum.

#### Supported operations

```js
above(key): Collection;
aboveOrEqual(key): Collection;
Expand Down Expand Up @@ -139,113 +210,76 @@ uniqueKeys(): Promise;
until(filter: (value) => boolean, includeStopEntry?: boolean): Collection;
update(key: Key, changes: { [keyPath: string]: any }): Promise;
```
This is a mix of methods from [WhereClause](https://dexie.org/docs/WhereClause/WhereClause), [Table](https://dexie.org/docs/Table/Table) and [Collection](https://dexie.org/docs/Collection/Collection). Dive into the [API reference](https://dexie.org/docs/API-Reference) to see the details.
#### Hello World (Typescript)
```js
import Dexie, { Table } from 'dexie';
interface Friend {
id?: number;
name?: string;
age?: number;
}

//
// Declare Database
//
class FriendDatabase extends Dexie {
public friends!: Table<Friend, number>; // id is number in this case

public constructor() {
super("FriendDatabase");
this.version(1).stores({
friends: "++id,name,age"
});
}
}
This is a mix of methods from [WhereClause](https://dexie.org/docs/WhereClause/WhereClause), [Table](https://dexie.org/docs/Table/Table) and [Collection](https://dexie.org/docs/Collection/Collection). Dive into the [API reference](https://dexie.org/docs/API-Reference) to see the details.
const db = new FriendDatabase();
## Dexie Cloud
db.transaction('rw', db.friends, async() => {
[Dexie Cloud](https://dexie.org/cloud/) is a commercial offering that can be used as an add-on to Dexie.js. It syncs a Dexie database with a server and enables developers to build apps without having to care about backend or database layer else than the frontend code with Dexie.js as the sole database layer.
// Make sure we have something in DB:
if ((await db.friends.where({name: 'Josephine'}).count()) === 0) {
const id = await db.friends.add({name: "Josephine", age: 21});
alert (`Addded friend with id ${id}`);
}
Source for a sample Dexie Cloud app: [Dexie Cloud To-do app](https://github.com/dexie/Dexie.js/tree/master/samples/dexie-cloud-todo-app)
// Query:
const youngFriends = await db.friends.where("age").below(25).toArray();
See the sample Dexie Cloud app in action: https://dexie.github.io/Dexie.js/dexie-cloud-todo-app/
// Show result:
alert ("My young friends: " + JSON.stringify(youngFriends));
## Samples
}).catch(e => {
alert(e.stack || e);
});
```
Samples
-------
https://dexie.org/docs/Samples
https://github.com/dexie/Dexie.js/tree/master/samples
Knowledge Base
-----
## Knowledge Base
[https://dexie.org/docs/Questions-and-Answers](https://dexie.org/docs/Questions-and-Answers)
Website
-------
## Website
[https://dexie.org](https://dexie.org)
Install over npm
----------------
## Install via npm
```
npm install dexie
```
## Download
Download
--------
For those who don't like package managers, here's the download links:
### Legacy:
### UMD (for legacy script includes as well as commonjs require):
https://unpkg.com/dexie@latest/dist/dexie.min.js
https://unpkg.com/dexie@latest/dist/dexie.min.js.map
### Modern:
### Modern (ES module):
https://unpkg.com/dexie@latest/dist/modern/dexie.min.mjs
https://unpkg.com/dexie@latest/dist/modern/dexie.min.mjs.map
### Typings:
https://unpkg.com/dexie@latest/dist/dexie.d.ts
https://unpkg.com/dexie@latest/dist/dexie.d.ts
# Contributing
Contributing
============
See [CONTRIBUTING.md](CONTRIBUTING.md)
Build
-----
## Build
```
pnpm install
pnpm run build
```
Test
----
## Test
```
pnpm test
```
Watch
-----
## Watch
```
pnpm run watch
```
Expand Down

0 comments on commit 28b22e2

Please sign in to comment.