@sanity-labs/groq-content-mapper 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,23 @@
 # @sanity-labs/groq-content-mapper
 
-Typed `.groq` file imports for TypeScript 7.1 and later. A query kept in its own file is imported as a string that carries its result and params types, inferred from your Sanity schema:
+Typed `.groq` file imports for TypeScript 7.1 and later. A query kept in its own file is imported as a string that carries its result and params types, inferred from your Sanity schema.
+
+## Requirements
+
+- **TypeScript 7.1 or later.** Content mappers do not exist in earlier versions. 7.1 is currently a beta: `npm install -D typescript@beta`.
+- **Node.js 22.12 or later.** On Node 26.5 and later, run `.groq` imports with `--experimental-import-text`, or with the preload below. On earlier Node, run `node --import @sanity-labs/groq-content-mapper/register`.
+- **Type-check with `tsc --runExternalCode`.** Without that flag the mapper does not run, and `.groq` imports are not typed.
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "typecheck": "tsc --noEmit --runExternalCode",
+  },
+}
+```
+
+## Usage
 
 ```groq
 // postsBySearch.groq
@@ -18,18 +35,17 @@ const posts = await client.fetch(postsBySearch, {searchQuery: 'foo', start: 0, e
 //    ^? QueryResponse, with the params checked
 ```
 
-This is experimental. It is a TypeScript 7.1 [content mapper](https://devblogs.microsoft.com/typescript/announcing-typescript-7-1-beta/): there is no generated declaration file, and nothing for earlier TypeScript releases. The type generation itself comes from [`@sanity/codegen`](https://github.com/sanity-io/codegen), which this package depends on, so you do not install it yourself.
+Types come from the file as it is. Nothing is written to disk, and nothing is added to the global scope.
 
 ## What an import gives you
 
-Each `.groq` file is a module with three exports:
+Each `.groq` file has three exports:
 
-- The default export is the query string, typed as its own literal with the result and params types attached as optional phantom properties. It is still assignable to `string`. The literal is the file's exact content, trailing newline included, because that is what a text import evaluates to.
-- `QueryResponse` is the result type, evaluated the way `defineQuery` results are, so `[0]` is `T | null`.
+- The default export is the query string, typed as its own text, and still assignable to `string`. The type includes the file's trailing newline, because that is what the import evaluates to.
+- `QueryResponse` is the result type. `[0]` is `T | null`.
 - `QueryParams` is the object the `$` placeholders expect. A placeholder compared with a field takes the field's type, `match` takes a string, slice bounds are numbers, and anything the schema says nothing about is `unknown`. A query without placeholders has `QueryParams = Record<string, never>`.
 
 ```ts
-// What './postsBySearch.groq' resolves to
 export type QueryResponse = Array<{_id: string; title: string | null; slug: Slug | null}>
 export type QueryParams = {searchQuery: string; start: number; end: number}
 declare const query: '*[_type == "post" && title match $searchQuery] …\n' & {
@@ -39,13 +55,13 @@ declare const query: '*[_type == "post" && title match $searchQuery] …\n' & {
 export default query
 ```
 
-Nothing is declared globally and nothing is imported. `@sanity/client` reads the brand structurally once [sanity-io/client#1373](https://github.com/sanity-io/client/pull/1373) is released, so `client.fetch(query, params)` infers both types. With an older client, pass the type yourself: `client.fetch<QueryResponse>(query, params)`. The brand is also exported as `GroqQuery<Query, Result, Params>`, with `GroqResult<Q>` and `GroqParams<Q>` to read it back.
+`client.fetch(query, params)` infers both types once `@sanity/client` includes [sanity-io/client#1373](https://github.com/sanity-io/client/pull/1373). With an older client, pass the type yourself: `client.fetch<QueryResponse>(query, params)`. `GroqQuery<Query, Result, Params>`, `GroqResult<Q>` and `GroqParams<Q>` are exported for the same shape.
 
 ### Imports
 
-A value import needs the `with {type: 'text'}` attribute, which is the standard text import ([TC39 import text](https://github.com/tc39/proposal-import-text)): at run time the default export is the file's content. TypeScript ignores the attribute and asks the content mapper for the type.
+A value import needs `with {type: 'text'}`, the [standard text import](https://github.com/tc39/proposal-import-text). At run time the default export is the file's content.
 
-A type-only import needs no attribute, and since it is erased it keeps the query string out of the bundle. Use it in code that only needs the types, such as components rendering a result:
+A type-only import needs no attribute. It is erased, so the query string stays out of the bundle:
 
 ```ts
 import type {QueryResponse} from './postsBySearch.groq'
@@ -53,31 +69,27 @@ import type {QueryResponse} from './postsBySearch.groq'
 export function PostList(props: {posts: QueryResponse}) {}
 ```
 
-When a file needs both the query and its types, write one statement with inline type specifiers:
+When a file needs both the query and its types, write one statement:
 
 ```ts
 import postsBySearch, {type QueryResponse} from './postsBySearch.groq' with {type: 'text'}
 ```
 
-rather than a value import plus a separate `import type` from the same file. ESLint's `import-x/no-duplicates` autofix merges the two and drops or mangles the attribute in the process.
+A separate `import type` from the same file gets merged by ESLint's `import-x/no-duplicates` autofix, which drops or mangles the attribute.
 
 ## Setup
 
-You need TypeScript 7.1 or later and Node 22.12 or later.
-
 ```sh
 npm install -D @sanity-labs/groq-content-mapper typescript@beta
 ```
 
-If your app runs `.groq` imports on Node through the `register` preload below (rather than as a bundle), install the package as a regular dependency instead.
-
-Write the schema file with the Sanity CLI:
+If the app runs `.groq` imports on Node through the preload (rather than as a bundle), install the package as a regular dependency instead.
 
 ```sh
 npx sanity schema extract
 ```
 
-Register the mapper in `tsconfig.json`, next to `compilerOptions`. The tsconfig is the only place it is configured, and `schema` is required:
+`schema` is required, and the tsconfig is the only configuration. Paths are relative to it:
 
 ```jsonc
 // tsconfig.json
@@ -93,22 +105,11 @@ Register the mapper in `tsconfig.json`, next to `compilerOptions`. The tsconfig
 }
 ```
 
-Paths are relative to the tsconfig. Type-check with `--runExternalCode`, the flag that lets `tsc` start content mappers:
-
-```jsonc
-// package.json
-{
-  "scripts": {
-    "typecheck": "tsc --noEmit --runExternalCode",
-  },
-}
-```
-
-The schema file is watched, so extracting it again retypes the imports. A file that cannot be typed, because the query does not parse or the schema is missing, still resolves, with `unknown` for what could not be inferred and a diagnostic saying why. GROQ syntax errors are reported at the `.groq` file as `error groq2`.
+Type-check with the `tsc --noEmit --runExternalCode` script above. The schema file is watched, so extracting it again retypes the imports. A query that does not parse, or a missing schema, still resolves: the unknown parts are `unknown`, and the diagnostic says why. A GROQ syntax error is reported on the `.groq` file as `error groq2`.
 
 ### Editor
 
-In VS Code or Cursor, install the TypeScript 7 extension (`TypeScriptTeam.native-preview`) and point it at the project's TypeScript, since the extension bundles 7.0:
+In VS Code or Cursor, install the TypeScript 7 extension (`TypeScriptTeam.native-preview`) and point it at the project's TypeScript. The extension bundles 7.0:
 
 ```jsonc
 // .vscode/settings.json
@@ -122,7 +123,7 @@ Trust the workspace, and allow the extension to use the workspace's TypeScript w
 
 ## One schema per folder
 
-A codebase that queries more than one project or dataset has one schema per folder. TypeScript registers a content mapper by file extension only, and rejects two entries for `.groq`, so the folders are listed inside the one entry with `schemas`:
+A codebase that queries more than one project or dataset has one schema per folder. TypeScript allows one mapper entry per extension, so list the folders inside that entry with `schemas`:
 
 ```jsonc
 {
@@ -141,9 +142,9 @@ A codebase that queries more than one project or dataset has one schema per fold
 }
 ```
 
-A file is typed against the schema of the deepest folder that contains it, and against `schema` when no folder does. Without a `schema`, a file outside every folder gets a diagnostic.
+A file uses the schema of the deepest folder that contains it, and `schema` when no folder does. Without a `schema`, a file outside every folder gets a diagnostic.
 
-Folders work well with a `package.json` `imports` alias. TypeScript resolves the alias to the file before asking the mapper, so each folder's schema still applies, and Node, Bun, Deno and the bundlers resolve `imports` themselves:
+A `package.json` `imports` alias resolves to the file, so the folder's schema still applies. Node, Bun, Deno and the bundlers resolve `imports` themselves:
 
 ```jsonc
 // package.json
@@ -161,7 +162,7 @@ import products from '#queries/shop/products.groq' with {type: 'text'}
 
 ## Running the imports
 
-At run time `with {type: 'text'}` makes the runtime or bundler deliver the file as a string. Many do this on their own; for the rest, this package has one entry each. None of them runs type generation.
+`with {type: 'text'}` makes the runtime or bundler deliver the file as a string. Where one does not, one line fills in.
 
 | Runtime or bundler                            | Setup                                                                   |
 | --------------------------------------------- | ----------------------------------------------------------------------- |
@@ -182,8 +183,6 @@ At run time `with {type: 'text'}` makes the runtime or bundler deliver the file
 node --import @sanity-labs/groq-content-mapper/register main.ts
 ```
 
-The preload uses `module.registerHooks` where Node has it (22.15 and later) and `module.register` before that.
-
 ### Vite, Vitest, Rollup
 
 ```ts
@@ -194,7 +193,7 @@ import {defineConfig} from 'vite'
 export default defineConfig({plugins: [groqFiles()]})
 ```
 
-Vite's dev server does not handle the attribute itself, so the plugin is needed there even where the build would work without it.
+Vite's dev server does not handle the attribute, so the plugin is needed there even when a production build would work without it.
 
 ### Next.js
 
@@ -205,7 +204,7 @@ import {withGroqFiles} from '@sanity-labs/groq-content-mapper/next'
 export default withGroqFiles(nextConfig)
 ```
 
-Turbopack handles the attribute on its own. The wrapper adds an `asset/source` rule for the webpack that Next bundles, which predates webpack's built-in support. It also takes over the type check `next build` runs: Next runs `tsc` without `--runExternalCode`, so its check fails on every `.groq` import. The wrapper turns Next's check off and runs the same check with the flag after the compile. If your config already sets `typescript.ignoreBuildErrors`, no check is run.
+`withGroqFiles` covers both Turbopack and the webpack Next bundles. It also replaces the type check `next build` runs, which does not pass `--runExternalCode` and so fails on every `.groq` import. The same check runs with the flag after the compile. If the config already sets `typescript.ignoreBuildErrors`, no check is run.
 
 ### Jest
 
@@ -216,12 +215,12 @@ export default {
 }
 ```
 
-Jest's ES module loader rejects `type: 'text'`, so this works for tests compiled to CommonJS, where Babel drops the attribute.
+Jest rejects `type: 'text'` in its ES module loader, so this is for tests compiled to CommonJS, where the attribute is dropped.
 
 ## Limitations
 
-- A comparison against `^` (the parent scope) types its placeholder as `unknown`.
-- groq-js does not model `score()` yet, so `_score` is typed as `null`, and a `[_score > 0]` filter empties the result type.
+- A comparison against `^` types its placeholder as `unknown`.
+- `score()` is not typed yet, so `_score` is `null`, and a `[_score > 0]` filter empties the result type.
 - `include` takes folders, not globs.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity-labs/groq-content-mapper",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Typed .groq file imports for TypeScript 7.1, from your Sanity schema",
   "keywords": [
     "content-mapper",
@@ -42,7 +42,7 @@
   "dependencies": {
     "@babel/generator": "^7.29.7",
     "@babel/types": "^7.29.7",
-    "@sanity/codegen": "^8.2.0",
+    "@sanity/codegen": "8.2.0",
     "groq-js": "^2.0.0",
     "valibot": "^1.4.2"
   },