@miichom/lodestone 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 miichom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @miichom/lodestone
+
+[![npm](https://img.shields.io/npm/v/@miichom/lodestone.svg)](https://www.npmjs.com/package/@miichom/lodestone)
+![node](https://img.shields.io/node/v/@miichom/lodestone)
+
+A **minimal, fully typed [Lodestone](https://na.finalfantasyxiv.com/lodestone/) client** for _[Final Fantasy XIV](https://www.finalfantasyxiv.com/)_, providing access to **all endpoints exposed by the Lodestone** through a consistent, schema-driven API.
+
+Designed for **server-side and worker runtimes**: [Node.js 20+](https://nodejs.org/), [Bun](https://bun.sh/), [Cloudflare Workers](https://developers.cloudflare.com/workers/), and [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
+
+## Why?
+
+Most Lodestone scrapers rely on DOM emulation (e.g. [JSDOM](https://github.com/jsdom/jsdom), [cheerio](https://cheerio.js.org/)), which increases bundle size, slows cold starts, and often breaks in edge or serverless environments.
+
+`@miichom/lodestone` avoids DOM dependencies entirely, using a **predictable, schema-driven parsing model** that works consistently across modern runtimes.
+
+## Features
+
+- 🪶 Lightweight and dependency-minimal
+- 🧭 Fully typed [TypeScript](https://www.typescriptlang.org/) API
+- ⚡ Edge- and serverless-friendly
+- 🧱 No DOM, no JSDOM, no cheerio
+- 🌐 Access to all Lodestone endpoints
+- 🔍 Search and lookup across supported resources
+- 🧩 Optional column-based data fetching
+
+## Install
+
+```bash
+npm install @miichom/lodestone
+```
+
+## Example usage
+
+```ts
+import Lodestone from "@miichom/lodestone";
+
+const ls = new Lodestone();
+
+// fetch a character
+const character = await ls.character.get(12345678);
+
+// fetch specific columns
+const partial = await ls.character.get(12345678, {
+  columns: ["mount"],
+});
+
+// search characters
+const results = await ls.character.find({
+  q: "Y'shtola",
+  worldname: "Twintania",
+});
+```
+
+> Additional Lodestone endpoints follow the same API pattern and are exposed through their respective namespaces.
+
+## Options
+
+The `Lodestone` constructor accepts a small set of configuration options.  
+These apply globally to all endpoints (`character`, `cwls`, `freecompany`, `linkshell`, `pvpteam`).
+
+```ts
+const ls = new Lodestone({
+  locale: "eu",
+  headers: {
+    "user-agent": "my-xiv-tool/1.0",
+  },
+});
+```
+
+### `locale?: "de" | "eu" | "fr" | "jp" | "na"`
+
+Selects which Lodestone region to target. Defaults to **`"na"`**.
+
+Each locale maps to its own Lodestone instance:
+
+- `na` → https://na.finalfantasyxiv.com/lodestone
+- `eu` → https://eu.finalfantasyxiv.com/lodestone
+- `jp` → https://jp.finalfantasyxiv.com/lodestone
+- `fr` → https://fr.finalfantasyxiv.com/lodestone
+- `de` → https://de.finalfantasyxiv.com/lodestone
+
+All requests made through the client automatically use the selected locale.
+
+### `headers?: Record<string, string>`
+
+Optional request headers applied to every Lodestone request.
+
+- Header keys are normalized to lowercase.
+- A default User‑Agent is always prepended:
+
+```
+curl/0.1.0 (+https://github.com/miichom/lodestone)
+```
+
+If you provide your own `user-agent`, it is appended:
+
+```ts
+headers: {
+  "user-agent": "my-app/1.0",
+}
+// → curl/0.1.0 (+https://github.com/miichom/lodestone) my-app/1.0
+```
+
+For more information on the `User-Agent` header, please see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent.
+
+> While optional, providing a custom User‑Agent is recommended for any automated or high‑volume usage.
+
+### Column options (for `get` only)
+
+Some endpoints (notably **characters**) expose additional “column” pages on Lodestone.  
+You can request them via the `columns` option:
+
+```ts
+const profile = await ls.character.get(12345678, {
+  columns: ["mount", "minion"],
+});
+```
+
+Columns are fetched lazily and merged into the returned object.
+
+## Attribution
+
+_Final Fantasy XIV_ and all related assets, including data accessed through the [Lodestone](https://na.finalfantasyxiv.com/lodestone/), are the intellectual property of &copy; [SQUARE ENIX CO., LTD.](https://www.square-enix.com/) All rights reserved.
+
+This project is not affiliated with or endorsed by Square Enix.
+
+# Contributing
+
+See [`CONTRIBUTING.md`](.github/CONTRIBUTING.md).
+
+# License
+
+See [`LICENSE.md`](./LICENSE.md).

package/dist/index.d.ts

@@ -0,0 +1,746 @@
+type Primitives = {
+    boolean: boolean;
+    number: number;
+    string: string;
+    date: Date;
+    url: URL;
+};
+type Primitive = keyof Primitives;
+type Selector = {
+    type: `${Primitive}[]` | Primitive;
+    selector: string;
+    attribute?: string;
+    regex?: RegExp;
+};
+type SelectorShape = {
+    shape: {
+        root: Selector;
+    } & Selectors;
+    type: "object[]";
+} | {
+    shape: Selectors;
+    type: "object";
+};
+type Selectors = {
+    [key: string]: Selector | SelectorShape;
+};
+type QueryShape = {
+    type: Primitive;
+    pattern?: RegExp;
+    required?: boolean;
+};
+type Registry = {
+    path: string;
+    item: {
+        fields: Selectors;
+        columns?: Selectors;
+    };
+    list: {
+        query: Record<string, QueryShape>;
+        fields: Selectors;
+    };
+};
+type ExtractPrimitive<T extends Primitive> = Primitives[T];
+type ExtractQuery<T extends QueryShape> = T["type"];
+type RequiredKeys<T> = {
+    [K in keyof T]: T[K] extends {
+        required: true;
+    } ? K : never;
+}[keyof T];
+type InferQuery<R extends Registry> = Partial<{
+    [K in keyof R["list"]["query"]]: ExtractPrimitive<ExtractQuery<R["list"]["query"][K]>>;
+}> & {
+    [K in RequiredKeys<R["list"]["query"]>]: ExtractPrimitive<ExtractQuery<R["list"]["query"][K]>>;
+};
+type InferSelectors<T extends Selectors> = {
+    [K in keyof T]: InferSelector<T[K]>;
+};
+type InferSelector<T> = T extends {
+    type: infer U;
+} ? U extends keyof Primitives ? Primitives[U] : U extends `${infer Base}[]` ? Base extends keyof Primitives ? Primitives[Base][] : Base extends "object" ? InferSelectors<T extends SelectorShape ? T["shape"] : never>[] : never : U extends "object" ? InferSelectors<T extends SelectorShape ? T["shape"] : never> : never : never;
+type InferItem<R extends Registry> = InferSelectors<R["item"]["fields"]>;
+type InferList<R extends Registry> = InferSelectors<R["list"]["fields"]>;
+type InferColumns<R extends Registry> = R["item"]["columns"] extends Selectors ? {
+    [K in keyof R["item"]["columns"]]: InferSelector<R["item"]["columns"][K]>;
+} : never;
+declare const character: {
+    item: {
+        columns: {
+            achievement: {
+                shape: {
+                    score: {
+                        selector: string;
+                        type: "number";
+                    };
+                    total: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "number";
+                    };
+                };
+                type: "object";
+            };
+            faceaccessory: {
+                selector: string;
+                type: "number";
+            };
+            minion: {
+                selector: string;
+                type: "number";
+            };
+            mount: {
+                selector: string;
+                type: "number";
+            };
+        };
+        fields: {
+            avatar: {
+                attribute: string;
+                selector: string;
+                type: "string";
+            };
+            bio: {
+                selector: string;
+                type: "string";
+            };
+            data_center: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            free_company: {
+                shape: {
+                    crest: {
+                        attribute: string;
+                        selector: string;
+                        type: "string[]";
+                    };
+                    id: {
+                        attribute: string;
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                    name: {
+                        selector: string;
+                        type: "string";
+                    };
+                };
+                type: "object";
+            };
+            grand_company: {
+                shape: {
+                    name: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                    rank: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                };
+                type: "object";
+            };
+            id: {
+                attribute: string;
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+            portrait: {
+                attribute: string;
+                selector: string;
+                type: "string";
+            };
+            pvp_team: {
+                shape: {
+                    crest: {
+                        attribute: string;
+                        selector: string;
+                        type: "string[]";
+                    };
+                    id: {
+                        attribute: string;
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                    name: {
+                        selector: string;
+                        type: "string";
+                    };
+                };
+                type: "object";
+            };
+            title: {
+                selector: string;
+                type: "string";
+            };
+            world_name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+        };
+    };
+    list: {
+        fields: {
+            avatar: {
+                attribute: string;
+                selector: string;
+                type: "string";
+            };
+            data_center: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            grand_company: {
+                shape: {
+                    name: {
+                        attribute: string;
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                    rank: {
+                        attribute: string;
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                };
+                type: "object";
+            };
+            id: {
+                attribute: string;
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+            world_name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+        };
+        query: {
+            blog_lang: {
+                pattern: RegExp;
+                type: "string";
+            };
+            classjob: {
+                pattern: RegExp;
+                type: "string";
+            };
+            gcid: {
+                pattern: RegExp;
+                type: "string";
+            };
+            order: {
+                pattern: RegExp;
+                type: "string";
+            };
+            q: {
+                required: true;
+                type: "string";
+            };
+            race_tribe: {
+                pattern: RegExp;
+                type: "string";
+            };
+            worldname: {
+                pattern: RegExp;
+                type: "string";
+            };
+        };
+    };
+    path: string;
+};
+declare const cwls: {
+    item: {
+        fields: {
+            data_center: {
+                selector: string;
+                type: "string";
+            };
+            formed: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            members: {
+                regex: RegExp;
+                selector: string;
+                type: "number";
+            };
+            name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+        };
+    };
+    list: {
+        fields: {
+            data_center: {
+                selector: string;
+                type: "string";
+            };
+            id: {
+                attribute: string;
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            members: {
+                selector: string;
+                type: "string";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+        };
+        query: {
+            cf_public: {
+                type: "boolean";
+            };
+            character_count: {
+                pattern: RegExp;
+                type: "string";
+            };
+            dcname: {
+                pattern: RegExp;
+                type: "string";
+            };
+            order: {
+                pattern: RegExp;
+                type: "string";
+            };
+            q: {
+                required: true;
+                type: "string";
+            };
+        };
+    };
+    path: string;
+};
+declare const freecompany: {
+    item: {
+        fields: {
+            crest: {
+                attribute: string;
+                selector: string;
+                type: "string[]";
+            };
+            data_center: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            estate: {
+                shape: {
+                    greeting: {
+                        selector: string;
+                        type: "string";
+                    };
+                    name: {
+                        selector: string;
+                        type: "string";
+                    };
+                    plot: {
+                        selector: string;
+                        type: "string";
+                    };
+                };
+                type: "object";
+            };
+            formed: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            grand_company: {
+                shape: {
+                    name: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                    rank: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                };
+                type: "object";
+            };
+            id: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            members: {
+                selector: string;
+                type: "number";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+            rank: {
+                selector: string;
+                type: "number";
+            };
+            rankings: {
+                shape: {
+                    monthly: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "number";
+                    };
+                    weekly: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "number";
+                    };
+                };
+                type: "object";
+            };
+            slogan: {
+                selector: string;
+                type: "string";
+            };
+            tag: {
+                selector: string;
+                type: "string";
+            };
+            world_name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+        };
+    };
+    list: {
+        fields: {
+            crest: {
+                attribute: string;
+                selector: string;
+                type: "string[]";
+            };
+            data_center: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            formed: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            grand_company: {
+                shape: {
+                    name: {
+                        regex: RegExp;
+                        selector: string;
+                        type: "string";
+                    };
+                };
+                type: "object";
+            };
+            has_estate: {
+                selector: string;
+                type: "boolean";
+            };
+            id: {
+                attribute: string;
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            members: {
+                selector: string;
+                type: "number";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+            world_name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+        };
+        query: {
+            activetime: {
+                pattern: RegExp;
+                type: "string";
+            };
+            activities: {
+                pattern: RegExp;
+                type: "string";
+            };
+            cf_public: {
+                type: "boolean";
+            };
+            character_count: {
+                pattern: RegExp;
+                type: "string";
+            };
+            gcid: {
+                pattern: RegExp;
+                type: "string";
+            };
+            house: {
+                pattern: RegExp;
+                type: "string";
+            };
+            join: {
+                type: "boolean";
+            };
+            order: {
+                pattern: RegExp;
+                type: "string";
+            };
+            q: {
+                required: true;
+                type: "string";
+            };
+            roles: {
+                pattern: RegExp;
+                type: "string";
+            };
+            worldname: {
+                pattern: RegExp;
+                type: "string";
+            };
+        };
+    };
+    path: string;
+};
+declare const linkshell: {
+    item: {
+        fields: {
+            data_center: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            members: {
+                regex: RegExp;
+                selector: string;
+                type: "number";
+            };
+            name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            world_name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+        };
+    };
+    list: {
+        fields: {
+            data_center: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            id: {
+                attribute: string;
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            members: {
+                regex: RegExp;
+                selector: string;
+                type: "number";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+            world_name: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+        };
+        query: {
+            cf_public: {
+                type: "boolean";
+            };
+            character_count: {
+                pattern: RegExp;
+                type: "string";
+            };
+            order: {
+                pattern: RegExp;
+                type: "string";
+            };
+            q: {
+                required: true;
+                type: "string";
+            };
+            worldname: {
+                pattern: RegExp;
+                type: "string";
+            };
+        };
+    };
+    path: string;
+};
+declare const pvpteam: {
+    item: {
+        fields: {
+            crest: {
+                attribute: string;
+                selector: string;
+                type: "string[]";
+            };
+            data_center: {
+                selector: string;
+                type: "string";
+            };
+            formed: {
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+        };
+    };
+    list: {
+        fields: {
+            crest: {
+                attribute: string;
+                selector: string;
+                type: "string[]";
+            };
+            data_center: {
+                selector: string;
+                type: "string";
+            };
+            id: {
+                attribute: string;
+                regex: RegExp;
+                selector: string;
+                type: "string";
+            };
+            name: {
+                selector: string;
+                type: "string";
+            };
+        };
+        query: {
+            cf_public: {
+                type: "boolean";
+            };
+            dcname: {
+                pattern: RegExp;
+                type: "string";
+            };
+            order: {
+                pattern: RegExp;
+                type: "string";
+            };
+            q: {
+                required: true;
+                type: "string";
+            };
+        };
+    };
+    path: string;
+};
+type Character = typeof character;
+type CWLS = typeof cwls;
+type Freecompany = typeof freecompany;
+type Linkshell = typeof linkshell;
+type PvpTeam = typeof pvpteam;
+
+type NumberResolvable = string | number;
+type EndpointOptions = {
+    headers?: Record<string, string>;
+    locale?: string;
+};
+declare class Endpoint<R extends Registry> {
+    protected readonly registry: R;
+    protected readonly options?: EndpointOptions | undefined;
+    /**
+     * A generic Lodestone endpoint used to search and get items from Lodestone.
+     * @param {T} registry The provided endpoint registry containing field selectors to obtain
+     * @param {EndpointOptions<R>} [options] Default method options to use when fetching from Lodestone.
+     * @since 0.1.0
+     */
+    constructor(registry: R, options?: EndpointOptions | undefined);
+    private check;
+    private req;
+    private fetchDocument;
+    private fetchColumn;
+    private isMissing;
+    private isValid;
+    private validate;
+    private getRawValue;
+    private applyRegex;
+    private coerce;
+    private extract;
+    /**
+     * @param {InferQuery<R>} query The raw query parameters used by the Lodestone search.
+     * @param {EndpointOptions} [options] Optional method overrides.
+     * @returns {Promise<InferList<R>[] | null>}
+     * @since 0.1.0
+     */
+    find(query: InferQuery<R>, options?: EndpointOptions): Promise<InferList<R>[] | null>;
+    /**
+     * @param {NumberResolvable} id The unique identifier for the Lodestone item.
+     * @param {EndpointOptions & { columns?: Array<keyof InferColumns<R>> }} [options] Optional method overrides.
+     * @returns {Promise<(InferItem<R> & Partial<InferColumns<R>) | null>}
+     * @since 0.1.0
+     */
+    get(id: NumberResolvable, options?: EndpointOptions & {
+        columns?: Array<keyof InferColumns<R>>;
+    }): Promise<(InferItem<R> & Partial<InferColumns<R>>) | null>;
+}
+
+declare class Lodestone {
+    readonly character: Endpoint<Character>;
+    readonly cwls: Endpoint<CWLS>;
+    readonly freecompany: Endpoint<Freecompany>;
+    readonly linkshell: Endpoint<Linkshell>;
+    readonly pvpteam: Endpoint<PvpTeam>;
+    /**
+     * @param {EndpointOptions} [options] Default method options to use when fetching from Lodestone.
+     * @example
+     * ```ts
+     * const lodestone = new Lodestone();
+     *
+     * const char = await lodestone.character.get(12345678);
+     * // { id: '12345678', ... }
+     * ```
+     * @since 0.1.0
+     */
+    constructor(options?: EndpointOptions);
+}
+
+export { Lodestone, Lodestone as default };

package/dist/index.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=(t,r,n)=>((t,r,n)=>r in t?e(t,r,{enumerable:!0,configurable:!0,writable:!0,value:n}):t[r]=n)(t,"symbol"!=typeof r?r+"":r,n);import{parseHTML as r}from"linkedom/worker";var n=class extends Error{constructor(e){super(e),Error.captureStackTrace(this),this.name="LodestoneError"}},s=class{constructor(e,r){this.registry=e,this.options=r,t(this,"isMissing",e=>null==e),t(this,"isValid",(e,t)=>{switch(t){case"number":return"number"==typeof e||!Number.isNaN(Number(e));case"boolean":return"boolean"==typeof e;case"date":return e instanceof Date||!Number.isNaN(Date.parse(String(e)));case"url":try{return new URL(String(e)),!0}catch{return!1}default:return"string"==typeof e}}),t(this,"validate",e=>{const t=this.registry.list.query;for(const r of Object.keys(e))if(!(r in t))throw new n(`Unknown query parameter "${r}".`);for(const[r,s]of Object.entries(t)){const t=e[r];if(s.required&&this.isMissing(t))throw new n(`Missing required query parameter "${r}".`);if(!this.isMissing(t)){if(!this.isValid(t,s.type))throw new n(`Query parameter "${r}" must be type ${s.type}.`);if(s.pattern&&!s.pattern.test(String(t)))throw new n(`Query parameter "${r}" does not match required pattern.`)}}})}check(e){const{status:t}=e;if(200!==t){if(302===t)throw new n("Lodestone redirected the request.");if(503===t)throw new n("Lodestone is undergoing maintenance.");if(t>=500)throw new n(`Lodestone server error (${t}).`);if(t>=400)throw new n(`Request failed with status ${t}.`)}}async req(e,t){const{headers:r={},locale:n="na"}=t??this.options,s=Object.fromEntries(Object.entries(r).map(([e,t])=>[e.toLowerCase(),String(t)])),a="curl/0.1.0 (+https://github.com/miichom/lodestone)";return s["user-agent"]=s["user-agent"]?`${a} ${s["user-agent"]}`:a,fetch(`https://${n}.finalfantasyxiv.com/lodestone/${this.registry.path}/${e.replace(/^\/+/,"")}`,{headers:s,method:"GET",redirect:"follow"})}async fetchDocument(e,t){const n=await this.req(e,t);if(!n.ok||404===n.status)return null;this.check(n);const{document:s}=r(await n.text());return!s||s.querySelector(".parts__zero")?null:s}async fetchColumn(e,t,r){const n=this.registry.item.columns?.[t];if(!n)return;const s=await this.fetchDocument(`${e.toString()}/${t}`,r);if(!s)return;if(!("shape"in n))return this.extract(s,{value:n}).value;if("object"===n.type)return this.extract(s,n.shape);const a=n.shape.root.selector;return[...s.querySelectorAll(a)].map(e=>this.extract(e,n.shape))}getRawValue(e,t){return t.attribute?e.getAttribute(t.attribute)??"":e.textContent.trim()??""}applyRegex(e,t){if(!t.regex)return e;const r=e.match(t.regex);if(!r)return"";if(r.groups){const[e]=Object.keys(r.groups);return r.groups[e]??""}return r[1]??""}coerce(e,t){switch(t){case"boolean":return"1"===e||"true"===e;case"number":return Number(e);case"date":return new Date(e);case"url":return new URL(e);default:return e}}extract(e,t){const r={};for(const[n,s]of Object.entries(t)){if("shape"in s){if("object"===s.type)r[n]=this.extract(e,s.shape);else{const t=[...e.querySelectorAll(s.shape.root.selector)];r[n]=t.map(e=>this.extract(e,s.shape))}continue}const t=s.type.endsWith("[]"),a=t?s.type.slice(0,-2):s.type;if(t){const t=[...e.querySelectorAll(s.selector)];r[n]=t.map(e=>{const t=this.getRawValue(e,s),r=this.applyRegex(t,s);return this.coerce(r,a)});continue}const i=e.querySelector(s.selector);if(!i){r[n]=void 0;continue}const c=this.getRawValue(i,s),o=this.applyRegex(c,s);r[n]=this.coerce(o,a)}return r}async find(e,t={}){this.validate(e);const r=new URLSearchParams(Object.fromEntries(Object.entries(e).filter(([,e])=>null!=e).map(([e,t])=>[e,"boolean"==typeof t?t?"1":"0":String(t)]))).toString(),n=await this.fetchDocument(`?${r}`,Object.assign(this.options??{},t));if(!n)return null;return[...n.querySelectorAll("div.entry")].map(e=>this.extract(e,this.registry.list.fields)).filter(e=>null!==e.id||void 0!==e.id)}async get(e,t={}){const{columns:r,...n}=Object.assign(this.options??{},t),s=await this.fetchDocument(e.toString(),n);if(!s)return null;const a=this.extract(s,this.registry.item.fields);if(r&&this.registry.item.columns)for(const t of r){const r=await this.fetchColumn(e,String(t),n);void 0!==r&&(a[t]=r)}return a}},a={item:{columns:{achievement:{shape:{score:{selector:".achievement__point",type:"number"},total:{regex:/^(?<name>\d+)/,selector:".parts__total",type:"number"}},type:"object"},faceaccessory:{selector:".faceaccessory__sort__total > span:nth-child(1)",type:"number"},minion:{selector:".minion__sort__total > span:nth-child(1)",type:"number"},mount:{selector:".minion__sort__total > span:nth-child(1)",type:"number"}},fields:{avatar:{attribute:"src",selector:".frame__chara__face > img:nth-child(1)",type:"string"},bio:{selector:".character__selfintroduction",type:"string"},data_center:{regex:/\[(?<datacenter>\w+)]/,selector:".frame__chara__world",type:"string"},free_company:{shape:{crest:{attribute:"src",selector:"div.character__freecompany__crest > div > img",type:"string[]"},id:{attribute:"href",regex:/lodestone\/freecompany\/(?<id>\d+)\//,selector:".character__freecompany__name > h4:nth-child(2) > a:nth-child(1)",type:"string"},name:{selector:".character__freecompany__name > h4:nth-child(2) > a:nth-child(1)",type:"string"}},type:"object"},grand_company:{shape:{name:{regex:/^(?<name>[^/]+)/,selector:"div.character-block:nth-child(4) > div:nth-child(2) > p:nth-child(2)",type:"string"},rank:{regex:/\/\s*(?<rank>.+)$/,selector:"div.character-block:nth-child(4) > div:nth-child(2) > p:nth-child(2)",type:"string"}},type:"object"},id:{attribute:"href",regex:/lodestone\/character\/(?<id>\d+)\//,selector:".frame__chara__link",type:"string"},name:{selector:"div.frame__chara__box:nth-child(2) > .frame__chara__name",type:"string"},portrait:{attribute:"src",selector:".js__image_popup > img:nth-child(1)",type:"string"},pvp_team:{shape:{crest:{attribute:"src",selector:".character__pvpteam__crest__image > img",type:"string[]"},id:{attribute:"href",regex:/lodestone\/pvpteam\/(?<id>[\da-z]+)\//,selector:".character__pvpteam__name > h4 > a",type:"string"},name:{selector:".character__pvpteam__name > h4 > a",type:"string"}},type:"object"},title:{selector:".frame__chara__title",type:"string"},world_name:{regex:/^(?<world>\w+)/,selector:".frame__chara__world",type:"string"}}},list:{fields:{avatar:{attribute:"src",selector:".entry__chara__face > img",type:"string"},data_center:{regex:/\[(?<datacenter>\w+)]/,selector:".entry__world",type:"string"},grand_company:{shape:{name:{attribute:"data-tooltip",regex:/^(?<name>[^/]+)/,selector:".entry__chara_info > .js__tooltip",type:"string"},rank:{attribute:"data-tooltip",regex:/\/\s*(?<rank>.+)$/,selector:".entry__chara_info > .js__tooltip",type:"string"}},type:"object"},id:{attribute:"href",regex:/lodestone\/character\/(?<id>\d+)\//,selector:".entry__link",type:"string"},name:{selector:".entry__name",type:"string"},world_name:{regex:/^(?<world>\w+)/,selector:".entry__world",type:"string"}},query:{blog_lang:{pattern:/^(?:ja|en|de|fr)$/,type:"string"},classjob:{pattern:/^(?:\d+|_job_(?:TANK|HEALER|MELEE|RANGED|CASTER|GATHERER|CRAFTER))$/,type:"string"},gcid:{pattern:/^[1-3]$/,type:"string"},order:{pattern:/^[18]?$/,type:"string"},q:{required:!0,type:"string"},race_tribe:{pattern:/^(?:race_\d+|tribe_\d+)$/,type:"string"},worldname:{pattern:/^(?:_dc_[A-Za-z]+|_region_[1-4]|[A-Za-z]+)$/,type:"string"}}},path:"character"},i={item:{fields:{data_center:{selector:".heading__cwls__dcname",type:"string"},formed:{regex:/ldst_strftime\((\d+),/,selector:".heading__cwls__formed > script",type:"string"},members:{regex:/(?<total>\d+)/,selector:"div.cf-member-list > .parts__total",type:"number"},name:{regex:/\s*(?<name>.+)/,selector:".heading__linkshell__name",type:"string"}}},list:{fields:{data_center:{selector:".entry__world",type:"string"},id:{attribute:"href",regex:/lodestone\/crossworld_linkshell\/(?<id>.+)\//,selector:".entry__link--line",type:"string"},members:{selector:".entry__linkshell__member > div > span",type:"string"},name:{selector:".entry__name",type:"string"}},query:{cf_public:{type:"boolean"},character_count:{pattern:/^(?:\d+-\d+|\d+-)$/,type:"string"},dcname:{pattern:/^(?:_dc_[A-Za-z]+|_region_[1-4])$/,type:"string"},order:{pattern:/^[16]?$/,type:"string"},q:{required:!0,type:"string"}}},path:"crossworld_linkshell"},c={item:{fields:{crest:{attribute:"src",selector:"div.ldst__window:nth-child(1) > div:nth-child(2) > a:nth-child(1) > div:nth-child(1) > div:nth-child(1) > div:nth-child(2) > img",type:"string[]"},data_center:{regex:/\[(?<datacenter>\w+)]/,selector:"p.entry__freecompany__gc:nth-child(2)",type:"string"},estate:{shape:{greeting:{selector:".freecompany__estate__greeting",type:"string"},name:{selector:".freecompany__estate__name",type:"string"},plot:{selector:".freecompany__estate__text",type:"string"}},type:"object"},formed:{regex:/ldst_strftime\((\d+),/,selector:"p.freecompany__text:nth-of-type(5) > script",type:"string"},grand_company:{shape:{name:{regex:/^(?<name>[^/]+)/,selector:"p.entry__freecompany__gc:nth-child(1)",type:"string"},rank:{regex:/\/\s*(?<rank>.+)$/,selector:"p.entry__freecompany__gc:nth-child(1)",type:"string"}},type:"object"},id:{regex:/lodestone\/freecompany\/(?<id>\d+)\//,selector:"a.entry__freecompany",type:"string"},members:{selector:"p.freecompany__text:nth-of-type(6)",type:"number"},name:{selector:"p.entry__freecompany__name",type:"string"},rank:{selector:"p.freecompany__text:nth-of-type(7)",type:"number"},rankings:{shape:{monthly:{regex:/Monthly Rank:(?<rank>\d+)/,selector:".character__ranking__data tr:nth-child(2) > th:nth-child(1)",type:"number"},weekly:{regex:/Weekly Rank:(?<rank>\d+)/,selector:".character__ranking__data tr:nth-child(1) > th:nth-child(1)",type:"number"}},type:"object"},slogan:{selector:".freecompany__text__message",type:"string"},tag:{selector:".freecompany__text.freecompany__text__tag",type:"string"},world_name:{regex:/^(?<world>\w+)/,selector:"p.entry__freecompany__gc:nth-child(2)",type:"string"}}},list:{fields:{crest:{attribute:"src",selector:".entry__freecompany__crest__image > img",type:"string[]"},data_center:{regex:/\[(?<datacenter>\w+)]/,selector:".entry__world:nth-child(3)",type:"string"},formed:{regex:/ldst_strftime\((\d+),/,selector:".entry__freecompany__fc-day > script",type:"string"},grand_company:{shape:{name:{regex:/^(?<name>[^/]+)/,selector:"p.entry__freecompany__gc:nth-child(1)",type:"string"}},type:"object"},has_estate:{selector:".entry__freecompany__fc-housing",type:"boolean"},id:{attribute:"href",regex:/lodestone\/freecompany\/(?<id>\d+)\//,selector:".entry__block",type:"string"},members:{selector:".entry__freecompany__fc-member",type:"number"},name:{selector:".entry__name",type:"string"},world_name:{regex:/^(?<world>\w+)/,selector:".entry__world:nth-child(3)",type:"string"}},query:{activetime:{pattern:/^[1-3]$/,type:"string"},activities:{pattern:/^(?:-1|[0-8])$/,type:"string"},cf_public:{type:"boolean"},character_count:{pattern:/^(?:\d+-\d+|\d+-)$/,type:"string"},gcid:{pattern:/^[1-3]$/,type:"string"},house:{pattern:/^[0-2]$/,type:"string"},join:{type:"boolean"},order:{pattern:/^[16]?$/,type:"string"},q:{required:!0,type:"string"},roles:{pattern:/^(?:-1|1[6-9]|20)$/,type:"string"},worldname:{pattern:/^(?:_dc_[A-Za-z]+|_region_[1-4]|[A-Za-z]+)$/,type:"string"}}},path:"freecompany"},o={item:{fields:{data_center:{regex:/\[(?<datacenter>\w+)]/,selector:".entry__world",type:"string"},members:{regex:/(?<total>\d+)/,selector:"div.cf-member-list > .parts__total",type:"number"},name:{regex:/\s*(?<name>.+)/,selector:".heading__linkshell__name",type:"string"},world_name:{regex:/^(?<world>\w+)/,selector:".entry__world",type:"string"}}},list:{fields:{data_center:{regex:/\[(?<datacenter>\w+)]/,selector:".entry__world",type:"string"},id:{attribute:"href",regex:/lodestone\/linkshell\/(?<id>.+)\//,selector:".entry__block",type:"string"},members:{regex:/(?<total>\d+)/,selector:".entry__linkshell__member > div > span",type:"number"},name:{selector:".entry__name",type:"string"},world_name:{regex:/^(?<world>\w+)/,selector:".entry__world",type:"string"}},query:{cf_public:{type:"boolean"},character_count:{pattern:/^(?:\d+-\d+|\d+-)$/,type:"string"},order:{pattern:/^[16]?$/,type:"string"},q:{required:!0,type:"string"},worldname:{pattern:/^(?:_region_[1-4]|[A-Za-z]+)$/,type:"string"}}},path:"linkshell"},l={item:{fields:{crest:{attribute:"src",selector:".entry__pvpteam__crest__image > img",type:"string[]"},data_center:{selector:".entry__pvpteam__name--dc",type:"string"},formed:{regex:/ldst_strftime\((\d+),/,selector:".entry__pvpteam__data--formed > script",type:"string"},name:{selector:".entry__pvpteam__name--team",type:"string"}}},list:{fields:{crest:{attribute:"src",selector:".entry__pvpteam__search__crest__image > img",type:"string[]"},data_center:{selector:".entry__world",type:"string"},id:{attribute:"href",regex:/lodestone\/pvpteam\/(?<id>.+)\//,selector:".entry__link",type:"string"},name:{selector:".entry__name",type:"string"}},query:{cf_public:{type:"boolean"},dcname:{pattern:/^(?:_dc_[A-Za-z]+|_region_[1-4])$/,type:"string"},order:{pattern:/^[16]?$/,type:"string"},q:{required:!0,type:"string"}}},path:"pvpteam"},_=class{constructor(e={}){t(this,"character"),t(this,"cwls"),t(this,"freecompany"),t(this,"linkshell"),t(this,"pvpteam"),this.character=new s(a,e),this.cwls=new s(i,e),this.freecompany=new s(c,e),this.linkshell=new s(o,e),this.pvpteam=new s(l,e)}},p=_;export{_ as Lodestone,p as default};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@miichom/lodestone",
+  "version": "0.1.0",
+  "description": "Fast, worker-safe Lodestone parsing ✨",
+  "keywords": [
+    "lodestone",
+    "ffxiv",
+    "final fantasy xiv",
+    "ffxiv data",
+    "scraper",
+    "dom parser",
+    "html parser",
+    "fast"
+  ],
+  "homepage": "https://github.com/miichom/lodestone#readme",
+  "bugs": {
+    "url": "https://github.com/miichom/lodestone/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miichom/lodestone.git"
+  },
+  "license": "MIT",
+  "author": "miichom <hello@cammy.xyz> (https://cammy.xyz/)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "test": "vitest",
+    "build": "tsup",
+    "format": "prettier --write .",
+    "lint": "eslint --ext .ts",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "linkedom": "^0.18.12"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@tsconfig/node20": "^20.1.8",
+    "@types/node": "^25.0.9",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-sort": "^4.0.0",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "globals": "^17.0.0",
+    "jiti": "^2.6.1",
+    "prettier": "^3.8.0",
+    "terser": "^5.46.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.0",
+    "vitest": "^4.0.17"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "packageManager": "pnpm@10.28.0"
+}