Skip to content

Zod migration for improved selector generation - #34

Draft
miichom wants to merge 24 commits into
xivapi:mainfrom
miichom:main
Draft

Zod migration for improved selector generation#34
miichom wants to merge 24 commits into
xivapi:mainfrom
miichom:main

Conversation

@miichom

@miichom miichom commented Aug 24, 2026

Copy link
Copy Markdown

This PR is related to xivapi/nodestone#20, please check out this issue before deciding whether this should be included here or kept internally for @xivapi/nodestone.

Summary

As apart of the discussion of merging @miichom/lodestone into @xivapi/nodestone for better discoverability but more importantly overall better typings for the original project that inspired it. The latest version of the package uses CSS selectors instead of this improved approach for handling the scraped data via Zod by providing accurate typings for TypeScript and other languages using JSON packages that support the draft-2020-12 schema.

Although, I have used personally XPath as the base as it was a artifact from when I was updating my package. If this is decided to switch to CSS as the base, supporting both XPath and CSS would still remain ideal for future support.

Changes made

  • Switch to Zod for schema generation ensuring compatibility with other languages using the latest standard JSON Schema.
  • No longer needing to using git submodule add for Node projects, importing it as git://github.com/miichom/lodestone-css-selectors as a dependency works just as well; import { ... } from "@xivapi/lodestone-css-selectors".
  • Added support for XPath expressions.

Unsure of including

  • pyproject.toml - allowing developers to install it via pip or uv on a git repo, similar to Node. (Tried, unsure if needed or works — need help on this if we want)

Todo

  • Add all the columns for character.json and test to make sure it works as expected.

Up for discussion

[Only for .ts files] I added transform into the Zod schemas, some Node projects may not need this included however it should not affect them if they don't use z.parse or z.safeParse - only if they import directly from src/index.ts or @xivapi/lodestone-css-selectors and use zod.

miichom and others added 24 commits August 20, 2026 16:20
…pteam, and metadata

- Implemented character schema with detailed profile, class/job, minion, mount, and face accessory structures.
- Created cwls schema for cross-world linkshell profiles and queries.
- Developed freecompany schema encompassing company details, members, and rankings.
- Added linkshell schema for linkshell profiles and member details.
- Introduced pvpteam schema for player versus player team profiles and member information.
- Established metadata enums for regions, datacenters, classes, jobs, races, and tribes.
- Added utility functions for XPath to CSS conversion and selector context management.
- Configured TypeScript settings for the project.
…tainability

- Introduced a new utility function `resolveSchema` in `src/lib/utils.ts` to enhance schema resolution with metadata.
- Removed outdated schemas: `character.ts`, `cwls.ts`, `freecompany.ts`, `linkshell.ts`, and `pvpteam.ts` to streamline the codebase.
- Updated `src/utils.ts` to eliminate the old selector utility, integrating its functionality into the new schema resolution process.
- Added a new TypeScript declaration file `zod.d.ts` to extend the Zod library with custom metadata types.
- Cleaned up the `src/schemas/index.ts` to reflect the removal of obsolete schemas.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant