data-of-loathing 3.1.2 → 3.1.3

package/README.md

@@ -1,21 +1,68 @@
 # data-of-loathing
 
-A client SDK for the data-of-loathing service.
+A typed client for querying Kingdom of Loathing game data. It wraps a SQLite database served by [data.loathers.net](https://data.loathers.net) and exposes it through a [MikroORM](https://mikro-orm.io) entity manager.
 
-## Browser usage
-
-The browser client uses [SQLocal](https://sqlocal.dev) (SQLite over WASM) under the hood. To use it in a browser app you will need to install the optional peer dependencies as dev dependencies:
+## Installation
 
 ```sh
-npm install -D sqlocal vite-plugin-node-polyfills
+npm install data-of-loathing
 ```
 
-### Vite
+## Node
+
+```ts
+import { createClient } from "data-of-loathing";
+
+const client = createClient();
+await client.load();
+
+const item = await client.query.findOne("Item", { name: "seal tooth" });
+console.log(item?.autosell); // 1
+```
 
-A Vite plugin is provided that handles the required configuration:
+The default strategy downloads the database from data.loathers.net and caches it to `~/.cache/data-of-loathing/`. It re-downloads only when the server's ETag changes.
+
+You can point it at a local file instead:
+
+```ts
+const client = createClient({ strategy: "local", path: "./dol.sqlite" });
+```
+
+## Browser
+
+Three strategies are available in the browser, each with different trade-offs.
+
+`"memory"` downloads the full database on each page load and holds it in memory. Simple, but slow to start on a cold load. Once the browser has cached the database file, however, it will be as fast as any other solution.
+
+```ts
+import { createClient } from "data-of-loathing";
+
+const client = createClient({ strategy: "memory" });
+```
+
+`"opfs"` downloads the database once and persists it to the [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system). Subsequent loads skip the download if the server's ETag matches.
+
+```ts
+const client = createClient({ strategy: "opfs" });
+```
+
+`"ranged"` never downloads the full database. It fetches only the SQLite pages it needs on demand using HTTP Range requests. This gives fast startup time at the cost of per-query network latency on a cold cache.
+
+```ts
+const client = createClient({ strategy: "ranged" });
+```
+
+All three accept a `url` option if you are hosting the database yourself:
+
+```ts
+const client = createClient({ strategy: "memory", url: "https://example.com/dol.sqlite" });
+```
+
+### Vite setup
+
+Add the plugin to your Vite config:
 
 ```ts
-// vite.config.ts
 import { defineConfig } from "vite";
 import dol from "data-of-loathing/vite";
 
@@ -24,19 +71,60 @@ export default defineConfig({
 });
 ```
 
-The plugin does two things by default:
+The plugin excludes the package and its SQLite WASM dependency from Vite's dependency optimiser, which is required for the worker URLs to resolve correctly. It also polyfills `Buffer`.
 
-- Configures Vite's dependency optimiser to prevent pre-bundling of the SQLite WASM
-- Polyfills `Buffer` (required by the underlying SQLite driver)
+If your deployment needs [cross-origin isolation headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) for other reasons, pass `{ coi: true }` to enable them on the dev server:
 
-#### OPFS strategy
+```ts
+plugins: [dol({ coi: true })]
+```
+
+## Querying
 
-If you use the `"opfs"` strategy, SQLite requires `SharedArrayBuffer` and `Atomics`, which in turn require cross-origin isolation headers. Pass `{ coi: true }` to enable them on the dev server:
+After `await client.load()`, `client.query` is a MikroORM `EntityManager`. The full MikroORM querying API is available, but the most common patterns are:
 
 ```ts
-export default defineConfig({
-  plugins: [dol({ coi: true })],
+const em = client.query;
+
+// find one record
+const item = await em.findOne("Item", { name: "seal tooth" });
+
+// find multiple records
+const familiars = await em.findAll("Familiar", {
+  where: { category: FamiliarCategory.Combat },
+  orderBy: { name: "asc" },
 });
+
+// find with a limit
+const skills = await em.find("Skill", {}, { limit: 10 });
 ```
 
-This sets `Cross-Origin-Embedder-Policy: credentialless` and `Cross-Origin-Opener-Policy: same-origin` on the dev server. For production you must set these headers at the hosting layer (e.g. Netlify `_headers`, Vercel `headers` config, nginx). The `credentialless` value is used rather than `require-corp` so cross-origin images are not blocked.
+## Entities
+
+The following entities are available to query:
+
+- `Item` - in-game items
+- `Effect` - status effects
+- `Skill` - skills usable by players
+- `Familiar` - familiars
+- `Monster` - monsters
+- `MonsterDrop` - individual item drops from monsters (relates `Monster` to `Item`)
+- `NativeMonster` - monsters that appear natively in a location (relates `Location` to `Monster`)
+- `Location` - in-game locations
+- `Path` - challenge paths
+- `AscensionClass` - player classes
+- `Equipment` - equipment items, with slot and stat requirements
+- `Consumable` - food and booze
+- `Concoction` - craftable items
+- `Ingredient` - ingredients for a concoction (relates `Concoction` to `Item`)
+- `Outfit` - outfits
+- `OutfitTreat` - the items that make up an outfit (relates `Outfit` to `Item`)
+- `FoldGroup` - groups of items that can be folded into each other
+- `ZapGroup` - groups of items that can be zapped into each other
+- `ItemModifiers` - numeric modifiers for an item (one-to-one with `Item`)
+- `EffectModifiers` - numeric modifiers for an effect (one-to-one with `Effect`)
+- `SkillModifiers` - numeric modifiers for a skill (one-to-one with `Skill`)
+- `FamiliarModifiers` - numeric modifiers for a familiar (one-to-one with `Familiar`)
+- `Meta` - metadata about the database, including the last update timestamp
+
+Enum types for filtering (`ItemUse`, `EffectQuality`, `SkillTag`, `FamiliarCategory`, `MonsterElement`, and others) are exported from the package alongside the entity types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-of-loathing",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "type": "module",
   "packageManager": "yarn@4.6.0",
   "repository": {
@@ -37,6 +37,7 @@
     "@mikro-orm/core": "^7.0.14",
     "@mikro-orm/sql": "^7.0.14",
     "@sqlite.org/sqlite-wasm": "~3.51.2-build9",
+    "env-paths": "^4.0.0",
     "kysely": "^0.28.17"
   },
   "devDependencies": {