kirby-types 0.7.2 → 1.0.0

package/README.md

@@ -20,16 +20,39 @@ yarn add -D kirby-types
 ## Basic Usage
 
 ```ts
-import type { KirbyQuery } from "kirby-types";
+import type { KirbyQuery, ParseKirbyQuery } from "kirby-types";
 
 // Strictly typed query
 const query: KirbyQuery = 'page.children.filterBy("featured", true)';
 
-// Invalid queries will throw a type error
-let invalidQuery: KirbyQuery;
-invalidQuery = "unknown"; // Not a valid model
-invalidQuery = 'site("'; // Empty parentheses
-invalidQuery = 'site("value"'; // Missing closing parenthesis
+// Parse query strings into structured objects
+type BasicQuery = ParseKirbyQuery<"site">;
+// Result: { model: "site"; chain: [] }
+
+type DotNotationQuery = ParseKirbyQuery<"page.children.listed">;
+// Result: {
+//   model: "page";
+//   chain: [
+//     { type: "property"; name: "children" },
+//     { type: "property"; name: "listed" }
+//   ]
+// }
+
+type MethodQuery = ParseKirbyQuery<'site("home")'>;
+// Result: {
+//   model: "site";
+//   chain: [{ type: "method"; name: "site"; params: '"home"' }]
+// }
+
+type ComplexQuery =
+  ParseKirbyQuery<'page.children.filterBy("status", "published")'>;
+// Result: {
+//   model: "page";
+//   chain: [
+//     { type: "property"; name: "children" },
+//     { type: "method"; name: "filterBy"; params: '"status", "published"' }
+//   ]
+// }
 ```
 
 ## API
@@ -44,6 +67,7 @@ By clicking on a type name, you will be redirected to the corresponding TypeScri
 
 - [`KirbyQueryModel`](./src/query.d.ts) - Matches any supported KirbyQL model.
 - [`KirbyQuery`](./src/query.d.ts) - Matches a KirbyQL [`query`](https://getkirby.com/docs/guide/blueprints/query-language).
+- [`ParseKirbyQuery`](./src/query.d.ts) - Parses a KirbyQL query string into a structured object with model and chain information.
 
 ### Blocks
 

package/index.d.ts

@@ -1,13 +1,18 @@
-export { KirbyApiResponse } from "./src/api";
-export {
+export type { KirbyApiResponse } from "./src/api";
+export type {
   KirbyBlock,
   KirbyDefaultBlocks,
   KirbyDefaultBlockType,
 } from "./src/blocks";
-export {
+export type {
   KirbyQueryRequest,
   KirbyQueryResponse,
   KirbyQuerySchema,
 } from "./src/kql";
-export { KirbyLayout, KirbyLayoutColumn } from "./src/layout";
-export { KirbyQuery, KirbyQueryChain, KirbyQueryModel } from "./src/query";
+export type { KirbyLayout, KirbyLayoutColumn } from "./src/layout";
+export type {
+  KirbyQuery,
+  KirbyQueryChain,
+  KirbyQueryModel,
+  ParseKirbyQuery,
+} from "./src/query";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "kirby-types",
   "type": "module",
-  "version": "0.7.2",
-  "packageManager": "pnpm@9.11.0",
+  "version": "1.0.0",
+  "packageManager": "pnpm@9.15.9",
   "description": "A collection of TypeScript types for the Kirby CMS",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -25,7 +25,7 @@
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.mjs"
+      "default": "./index.js"
     }
   },
   "types": "./index.d.ts",
@@ -42,11 +42,11 @@
     "test": "tsd -f \"test/**/*.test-d.ts\""
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^3.7.1",
-    "bumpp": "^9.5.2",
-    "eslint": "^9.10.0",
-    "prettier": "^3.3.3",
-    "tsd": "^0.31.2",
-    "typescript": "^5.5.4"
+    "@antfu/eslint-config": "^3.16.0",
+    "bumpp": "^9.11.1",
+    "eslint": "^9.27.0",
+    "prettier": "^3.5.3",
+    "tsd": "^0.32.0",
+    "typescript": "^5.8.3"
   }
 }

package/src/query.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Represents all supported model names in Kirby Query Language.
+ *
+ * This type includes all built-in Kirby models that can be used as the starting point
+ * for queries, plus any custom models you define.
+ *
+ * Built-in models include:
+ * - `site` - The site object
+ * - `page` - A page object
+ * - `user` - A user object
+ * - `file` - A file object
+ * - `collection` - A collection object
+ * - `kirby` - The Kirby instance
+ * - `content` - Content field data
+ * - `item` - Generic item in collections
+ * - `arrayItem` - An item in an array
+ * - `structureItem` - An item in a structure field
+ * - `block` - A block in the blocks field
+ *
+ * @example
+ * ```ts
+ * // Using built-in models
+ * const siteModel: KirbyQueryModel = "site";
+ * const pageModel: KirbyQueryModel = "page";
+ *
+ * // Using with custom models
+ * type CustomModels = "product" | "category";
+ * const customModel: KirbyQueryModel<CustomModels> = "product";
+ * ```
+ *
+ * @template CustomModel - Additional custom model names to include
+ */
 export type KirbyQueryModel<CustomModel extends string = never> =
   | "collection"
   | "kirby"
@@ -12,22 +44,204 @@ export type KirbyQueryModel<CustomModel extends string = never> =
   | "block"
   | CustomModel;
 
-// For simple dot-based queries like `site.title`, `page.images`, etc.
+/**
+ * Helper type for dot notation queries (e.g., `model.property.method`).
+ * @internal
+ */
 type DotNotationQuery<M extends string = never> =
   `${KirbyQueryModel<M>}.${string}`;
 
-// For function-based queries like `page("id")`, `user("name")`, etc.
+/**
+ * Helper type for function notation queries (e.g., `model(params)` or `model(params).chain`).
+ * @internal
+ */
 type FunctionNotationQuery<M extends string = never> =
-  `${KirbyQueryModel<M>}(${string})${string}`;
+  | `${KirbyQueryModel<M>}(${string})`
+  | `${KirbyQueryModel<M>}(${string})${string}`;
 
-// Combines the two types above to allow for either dot or function notation
+/**
+ * Represents query chains that extend beyond a simple model name.
+ *
+ * This type covers all valid query patterns that start with a model and include
+ * additional property access or method calls:
+ *
+ * - **Dot notation**: `model.property.method()`
+ * - **Function calls**: `model(params)`
+ * - **Mixed chains**: `model(params).property.method()`
+ *
+ * @example
+ * ```ts
+ * // Dot notation queries
+ * const dotQuery: KirbyQueryChain = "page.children.listed";
+ * const methodQuery: KirbyQueryChain = "page.children.filterBy('featured', true)";
+ *
+ * // Function notation queries
+ * const funcQuery: KirbyQueryChain = 'site("home")';
+ * const mixedQuery: KirbyQueryChain = 'page("blog").children.sortBy("date")';
+ *
+ * // With custom models
+ * type CustomModels = "product" | "category";
+ * const customQuery: KirbyQueryChain<CustomModels> = "product.price";
+ * ```
+ *
+ * @template M - Optional custom model names to include in validation
+ */
 export type KirbyQueryChain<M extends string = never> =
   | DotNotationQuery<M>
   | FunctionNotationQuery<M>;
 
+/**
+ * Represents any valid Kirby Query Language (KQL) string.
+ *
+ * This is the main type for validating KQL queries. It accepts:
+ * - Simple model names (e.g., `"site"`, `"page"`)
+ * - Property chains (e.g., `"page.children.listed"`)
+ * - Method calls (e.g., `'site("home")'`, `'page.filterBy("status", "published")'`)
+ * - Complex mixed queries (e.g., `'page("blog").children.filterBy("featured", true).sortBy("date")'`)
+ *
+ * Invalid queries (unknown models, malformed syntax) will be rejected at the type level.
+ *
+ * @example
+ * ```ts
+ * // Valid queries
+ * const simpleQuery: KirbyQuery = "site";
+ * const propertyQuery: KirbyQuery = "page.children.listed";
+ * const methodQuery: KirbyQuery = 'page.filterBy("featured", true)';
+ * const complexQuery: KirbyQuery = 'site("home").children.sortBy("date", "desc").limit(10)';
+ *
+ * // Custom models
+ * type MyModels = "product" | "category";
+ * const customQuery: KirbyQuery<MyModels> = "product.price";
+ *
+ * // Invalid queries (these will cause TypeScript errors)
+ * // const invalid: KirbyQuery = "unknownModel"; // ❌ Unknown model
+ * // const invalid: KirbyQuery<MyModels> = "user"; // ❌ Not in custom models
+ * ```
+ *
+ * @template CustomModel - Optional custom model names to include alongside built-in models
+ */
 export type KirbyQuery<CustomModel extends string = never> =
   | KirbyQueryModel<CustomModel>
-  // Ensures that it must match the pattern exactly, but not more broadly
   | (string extends KirbyQueryChain<CustomModel>
       ? never
       : KirbyQueryChain<CustomModel>);
+
+/**
+ * Parses a Kirby Query Language (KQL) string into a structured object.
+ *
+ * This type breaks down a query string into its constituent parts:
+ * - `model`: The root model the query starts with (e.g., `site`, `page`, `user`)
+ * - `chain`: An array of query segments representing the method calls and property accesses
+ *
+ * @example
+ * ```ts
+ * // Basic model query
+ * type Basic = ParseKirbyQuery<"site">;
+ * // Result: { model: "site"; chain: [] }
+ *
+ * // Property chain query
+ * type Props = ParseKirbyQuery<"page.children.listed">;
+ * // Result: {
+ * //   model: "page";
+ * //   chain: [
+ * //     { type: "property"; name: "children" },
+ * //     { type: "property"; name: "listed" }
+ * //   ]
+ * // }
+ *
+ * // Method call query
+ * type Method = ParseKirbyQuery<'site("home")'>;
+ * // Result: {
+ * //   model: "site";
+ * //   chain: [{ type: "method"; name: "site"; params: '"home"' }]
+ * // }
+ *
+ * // Complex query with mixed property and method calls
+ * type Complex = ParseKirbyQuery<'page.children.filterBy("featured", true).sortBy("date")'>;
+ * // Result: {
+ * //   model: "page";
+ * //   chain: [
+ * //     { type: "property"; name: "children" },
+ * //     { type: "method"; name: "filterBy"; params: '"featured", true' },
+ * //     { type: "method"; name: "sortBy"; params: '"date"' }
+ * //   ]
+ * // }
+ * ```
+ *
+ * @template T - The query string to parse
+ * @template M - Optional custom model names to include in validation
+ */
+export type ParseKirbyQuery<T extends string, M extends string = never> =
+  // Case 1: Simple model name (e.g., "site", "page")
+  T extends KirbyQueryModel<M>
+    ? { model: T; chain: [] }
+    : // Case 2: Dot notation (e.g., "page.children.listed")
+      T extends `${infer Model}.${infer Chain}`
+      ? Model extends KirbyQueryModel<M>
+        ? { model: Model; chain: ParseQueryChain<Chain> }
+        : never
+      : // Case 3: Method call only (e.g., 'site("home")')
+        T extends `${infer Model}(${infer Params})`
+        ? Model extends KirbyQueryModel<M>
+          ? { model: Model; chain: [ParseQuerySegment<T>] }
+          : never
+        : // Case 4: Method call followed by chain (e.g., 'site("home").children')
+          T extends `${infer Model}(${infer Params})${infer Rest}`
+          ? Model extends KirbyQueryModel<M>
+            ? Rest extends `.${infer Chain}`
+              ? {
+                  model: Model;
+                  chain: [
+                    ParseQuerySegment<`${Model}(${Params})`>,
+                    ...ParseQueryChain<Chain>,
+                  ];
+                }
+              : never
+            : never
+          : never;
+
+/**
+ * Recursively parses a chain of query segments separated by dots.
+ *
+ * @example
+ * ```ts
+ * type Chain = ParseQueryChain<"children.listed.first">;
+ * // Result: [
+ * //   { type: "property"; name: "children" },
+ * //   { type: "property"; name: "listed" },
+ * //   { type: "property"; name: "first" }
+ * // ]
+ * ```
+ *
+ * @internal
+ */
+type ParseQueryChain<T extends string> =
+  T extends `${infer First}.${infer Rest}`
+    ? [ParseQuerySegment<First>, ...ParseQueryChain<Rest>]
+    : [ParseQuerySegment<T>];
+
+/**
+ * Parses a single query segment to determine if it's a property access or method call.
+ *
+ * @example
+ * ```ts
+ * type Property = ParseQuerySegment<"children">;
+ * // Result: { type: "property"; name: "children" }
+ *
+ * type Method = ParseQuerySegment<'filterBy("status", "published")'>;
+ * // Result: { type: "method"; name: "filterBy"; params: '"status", "published"' }
+ * ```
+ *
+ * @internal
+ */
+type ParseQuerySegment<T extends string> =
+  T extends `${infer Name}(${infer Params})`
+    ? {
+        type: "method";
+        name: Name;
+        params: Params;
+      }
+    : {
+        type: "property";
+        name: T;
+      };