@izumisy-tailor/tailor-data-viewer 0.2.10 → 0.2.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@izumisy-tailor/tailor-data-viewer",
   "private": false,
-  "version": "0.2.10",
+  "version": "0.2.12",
   "type": "module",
   "description": "Flexible data viewer component for Tailor Platform",
   "files": [

package/src/component/collection/use-collection.ts

@@ -9,8 +9,9 @@ import type {
   UseCollectionOptions,
   UseCollectionReturn,
   ExtractQueryVariables,
+  ValidateCollectionQuery,
 } from "../types";
-import type { FieldName } from "../types";
+import type { FieldName, OrderableFieldName } from "../types";
 
 /**
  * Resolves query variables type: uses `ExtractQueryVariables<TQuery>` when
@@ -57,7 +58,11 @@ export function useCollection<
   > & {
     metadata: TMetadata;
     tableName: TTableName;
-    query: TQuery;
+    query: ValidateCollectionQuery<
+      TQuery,
+      FieldName<TMetadata, TTableName>,
+      OrderableFieldName<TMetadata, TTableName>
+    >;
   },
 ): UseCollectionReturn<
   FieldName<TMetadata, TTableName>,

package/src/component/collection/use-collection.typetest.ts

@@ -0,0 +1,185 @@
+/**
+ * Compile-time type tests for `ValidateCollectionQuery`.
+ *
+ * These tests verify that `useCollection` produces type errors when the
+ * query document's variables are incompatible with the collection's
+ * metadata fields.
+ *
+ * To run: `npx tsc --noEmit` — any assertion that evaluates to `never`
+ * will cause a compile error, ensuring the test cases stay enforced.
+ */
+
+import type {
+  ValidateCollectionQuery,
+  HasCollectionQueryError,
+  ExtractQueryInputKeys,
+  ExtractOrderField,
+} from "../types";
+
+// =============================================================================
+// Helpers – minimal branded document types mimicking gql-tada output
+// =============================================================================
+
+/** Helper to build a fake TypedDocumentNode with variable types */
+type FakeDoc<Variables> = {
+  __apiType?: (variables: Variables) => unknown;
+  kind: "Document";
+};
+
+// =============================================================================
+// 1. Variable key checks
+// =============================================================================
+
+// ✅ Query with standard Tailor variables should pass
+type DocOk = FakeDoc<{
+  first?: number | null;
+  after?: string | null;
+  query?: { name?: unknown } | null;
+  order?: readonly { field?: "name" | null }[] | null;
+}>;
+type Pass1 = ValidateCollectionQuery<DocOk, "name">;
+type Assert1 = HasCollectionQueryError<Pass1> extends true ? never : true;
+export const assert1: Assert1 = true;
+
+// ❌ Query missing $first should fail
+type DocNoFirst = FakeDoc<{
+  after?: string | null;
+  query?: { name?: unknown } | null;
+}>;
+type Fail1 = ValidateCollectionQuery<DocNoFirst, "name">;
+type AssertFail1 = HasCollectionQueryError<Fail1> extends true ? true : never;
+export const assertFail1: AssertFail1 = true;
+
+// =============================================================================
+// 2. OrderInput field compatibility
+// =============================================================================
+
+// ❌ Metadata has "name" | "email" but OrderInput only allows "name"
+type DocNarrowOrder = FakeDoc<{
+  first?: number | null;
+  order?: readonly { field?: "name" | null }[] | null;
+}>;
+type Fail2 = ValidateCollectionQuery<DocNarrowOrder, "name" | "email">;
+type AssertFail2 = HasCollectionQueryError<Fail2> extends true ? true : never;
+export const assertFail2: AssertFail2 = true;
+
+// ✅ OrderInput allows all metadata fields
+type DocWideOrder = FakeDoc<{
+  first?: number | null;
+  order?: readonly { field?: "name" | "email" | "phone" | null }[] | null;
+}>;
+type Pass2 = ValidateCollectionQuery<DocWideOrder, "name" | "email">;
+type AssertPass2 = HasCollectionQueryError<Pass2> extends true ? never : true;
+export const assertPass2: AssertPass2 = true;
+
+// =============================================================================
+// 3. QueryInput key compatibility
+// =============================================================================
+
+// ❌ Metadata has "name" | "phone" but QueryInput only has "name"
+type DocNarrowQuery = FakeDoc<{
+  first?: number | null;
+  query?: { name?: unknown } | null;
+  order?: readonly { field?: "name" | "phone" | null }[] | null;
+}>;
+type Fail3 = ValidateCollectionQuery<DocNarrowQuery, "name" | "phone">;
+type AssertFail3 = HasCollectionQueryError<Fail3> extends true ? true : never;
+export const assertFail3: AssertFail3 = true;
+
+// ✅ QueryInput has all metadata fields
+type DocWideQuery = FakeDoc<{
+  first?: number | null;
+  query?: { name?: unknown; phone?: unknown; email?: unknown } | null;
+  order?: readonly { field?: "name" | "phone" | "email" | null }[] | null;
+}>;
+type Pass3 = ValidateCollectionQuery<DocWideQuery, "name" | "phone">;
+type AssertPass3 = HasCollectionQueryError<Pass3> extends true ? never : true;
+export const assertPass3: AssertPass3 = true;
+
+// =============================================================================
+// 4. Variable name typo detection
+// =============================================================================
+
+// Query uses $filter instead of $query (typo) — no $query key in variables.
+// With metadata, there is no "query" key so QueryInput check is skipped.
+// But if the order is also correct, this particular typo would not be caught
+// at the useCollection level. It WILL be caught when spreading into useQuery()
+// because urql checks that variables match the document.
+type DocFilterTypo = FakeDoc<{
+  first?: number | null;
+  filter?: { name?: unknown } | null;
+  order?: readonly { field?: "name" | null }[] | null;
+}>;
+type Typo1 = ValidateCollectionQuery<DocFilterTypo, "name">;
+type AssertTypo1 = HasCollectionQueryError<Typo1> extends true ? never : true;
+export const assertTypo1: AssertTypo1 = true;
+
+// =============================================================================
+// 5. No gql-tada (plain DocumentNode) — all checks skipped
+// =============================================================================
+
+type PlainDoc = { kind: "Document" };
+type Pass5 = ValidateCollectionQuery<PlainDoc, "name">;
+type AssertPass5 = HasCollectionQueryError<Pass5> extends true ? never : true;
+export const assertPass5: AssertPass5 = true;
+
+// =============================================================================
+// 6. No metadata (string field names) — field-level checks skipped
+// =============================================================================
+
+type Pass6 = ValidateCollectionQuery<DocOk>;
+type AssertPass6 = HasCollectionQueryError<Pass6> extends true ? never : true;
+export const assertPass6: AssertPass6 = true;
+
+// =============================================================================
+// 7. Helper type tests
+// =============================================================================
+
+// ExtractOrderField
+type OrderField1 = ExtractOrderField<{
+  order?: readonly { field?: "a" | "b" | null }[] | null;
+}>;
+export const of1: OrderField1 = "a";
+export const of2: OrderField1 = "b";
+
+// ExtractQueryInputKeys
+type QIKeys1 = ExtractQueryInputKeys<
+  FakeDoc<{ query?: { name?: unknown; email?: unknown } | null }>
+>;
+export const qk1: QIKeys1 = "name";
+export const qk2: QIKeys1 = "email";
+
+// =============================================================================
+// 8. Mixed: $order present but no $query — only OrderInput checked
+// =============================================================================
+
+// ✅ No $query, order fields match
+type DocOrderOnly = FakeDoc<{
+  first?: number | null;
+  order?: readonly { field?: "name" | "email" | null }[] | null;
+}>;
+type Pass8 = ValidateCollectionQuery<DocOrderOnly, "name" | "email">;
+type AssertPass8 = HasCollectionQueryError<Pass8> extends true ? never : true;
+export const assertPass8: AssertPass8 = true;
+
+// =============================================================================
+// 9. Mixed: $query present but no $order — only QueryInput checked
+// =============================================================================
+
+// ✅ No $order, query keys match
+type DocQueryOnly = FakeDoc<{
+  first?: number | null;
+  query?: { name?: unknown; email?: unknown } | null;
+}>;
+type Pass9 = ValidateCollectionQuery<DocQueryOnly, "name" | "email">;
+type AssertPass9 = HasCollectionQueryError<Pass9> extends true ? never : true;
+export const assertPass9: AssertPass9 = true;
+
+// ❌ No $order, but query keys don't cover metadata fields
+type DocQueryOnlyMissing = FakeDoc<{
+  first?: number | null;
+  query?: { name?: unknown } | null;
+}>;
+type Fail9 = ValidateCollectionQuery<DocQueryOnlyMissing, "name" | "email">;
+type AssertFail9 = HasCollectionQueryError<Fail9> extends true ? true : never;
+export const assertFail9: AssertFail9 = true;

package/src/component/index.ts

@@ -28,8 +28,12 @@ export type {
   DataTableRowProps,
   DataTableCellProps,
   FieldName,
+  OrderableFieldName,
   ExtractOrderField,
   ExtractQueryVariables,
+  ExtractQueryInputKeys,
+  ValidateCollectionQuery,
+  HasCollectionQueryError,
   MatchingTableName,
   MetadataFieldOptions,
   MetadataFieldsOptions,

package/src/component/types.ts

@@ -582,6 +582,41 @@ export type FieldName<
     : never
   : never;
 
+/**
+ * Field types that support ordering.
+ * Mirrors the runtime `fieldTypeToSortConfig` logic — types that return
+ * a `SortConfig` (not `undefined`) are considered orderable.
+ */
+type OrderableFieldType =
+  | "string"
+  | "number"
+  | "boolean"
+  | "datetime"
+  | "date"
+  | "time"
+  | "enum";
+
+/**
+ * Extract only orderable field names from table metadata.
+ *
+ * Fields whose `type` is not in `OrderableFieldType` (e.g. `uuid`, `array`,
+ * `nested`, `file`) are excluded.  This allows `CheckOrderField` to compare
+ * only the fields that Tailor Platform actually exposes in the
+ * `OrderFieldEnum`, avoiding false positives for fields like `id`.
+ */
+export type OrderableFieldName<
+  TMetadata extends TableMetadataMap,
+  TTableName extends keyof TMetadata,
+> =
+  Extract<
+    TMetadata[TTableName]["fields"][number],
+    { readonly type: OrderableFieldType }
+  > extends { readonly name: infer N }
+    ? N extends string
+      ? N
+      : never
+    : never;
+
 /**
  * Extract the `order[].field` union type from a GraphQL variables type.
  *
@@ -620,6 +655,135 @@ export type ExtractQueryVariables<T> = T extends {
   ? NonNullable<V>
   : never;
 
+// =============================================================================
+// Collection Query Validation (compile-time safety)
+// =============================================================================
+
+/**
+ * Extract the key names of the `query` (filter) input type from GraphQL variables.
+ *
+ * For gql-tada's `VariablesOf<typeof QUERY>`, this extracts the allowed
+ * field names from the `query` (QueryInput) parameter.
+ *
+ * @example
+ * ```ts
+ * // query: BuyerContactQueryInput has keys: name, email, phone, ...
+ * type Keys = ExtractQueryInputKeys<typeof GET_BUYER_CONTACTS>;
+ * // → "name" | "email" | "phone" | ...
+ * ```
+ */
+export type ExtractQueryInputKeys<T> =
+  ExtractQueryVariables<T> extends {
+    query?: infer Q | null;
+  }
+    ? keyof NonNullable<Q> & string
+    : string;
+
+// ---------------------------------------------------------------------------
+// Individual collection query validation rules
+// ---------------------------------------------------------------------------
+// Each rule resolves to `Pass` when the check passes (or is not applicable),
+// or `{ __xxxError: "…" }` when it fails.  The rules are independent, so
+// adding a new one is just defining a new `Check*` type and appending it to
+// the intersection inside `ValidateCollectionQuery`.
+// ---------------------------------------------------------------------------
+
+/**
+ * Identity type for intersection: `T & Pass` ≡ `T`.
+ * Used as the "pass" branch of each validation rule.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+type Pass = {};
+
+/**
+ * Rule 1 — The query must declare `$first` as a variable.
+ */
+type CheckFirstVariable<TQuery> =
+  "first" extends keyof ExtractQueryVariables<TQuery>
+    ? Pass
+    : {
+        __firstVariableError: `Query must declare a $first variable (e.g. $first: Int).`;
+      };
+
+/**
+ * Rule 2 — When both metadata and `$order` variable exist, metadata field
+ * names must be assignable to the `field` enum inside the `OrderInput` type.
+ * Skipped when `TFieldName` is the generic `string` (no metadata).
+ */
+type CheckOrderField<
+  TQuery,
+  TFieldName extends string,
+> = "order" extends keyof ExtractQueryVariables<TQuery>
+  ? [TFieldName] extends [ExtractOrderField<ExtractQueryVariables<TQuery>>]
+    ? Pass
+    : {
+        __orderFieldError: `Some metadata field names are not assignable to OrderInput field enum. Check that the order variable's field type includes all metadata fields.`;
+      }
+  : Pass;
+
+/**
+ * Rule 3 — When both metadata and `$query` variable exist, metadata field
+ * names must be a subset of the `QueryInput` type's keys.
+ * Skipped when `TFieldName` is the generic `string` (no metadata).
+ */
+type CheckQueryInput<
+  TQuery,
+  TFieldName extends string,
+> = "query" extends keyof ExtractQueryVariables<TQuery>
+  ? [Exclude<TFieldName, ExtractQueryInputKeys<TQuery>>] extends [never]
+    ? Pass
+    : {
+        __queryInputError: `Some metadata field names are not present in QueryInput keys. Missing: ${Exclude<TFieldName, ExtractQueryInputKeys<TQuery>> & string}`;
+      }
+  : Pass;
+
+/**
+ * Validate that a query document is compatible with `useCollection`.
+ *
+ * When gql-tada type information is available (i.e. `ExtractQueryVariables`
+ * does not resolve to `never`), this type performs compile-time checks by
+ * intersecting independent rule types:
+ *
+ * 1. **`CheckFirstVariable`** — `$first` must exist.
+ * 2. **`CheckOrderField`** — OrderInput field compatibility (metadata-aware).
+ * 3. **`CheckQueryInput`** — QueryInput key compatibility (metadata-aware).
+ *
+ * Each rule resolves to `{}` on pass or `{ __xxxError: "…" }` on fail.
+ * A failing rule adds a phantom error property that makes `TQuery`
+ * incompatible with the actual value, producing a compile error.
+ *
+ * When gql-tada is not used (plain `DocumentNode`), all checks are skipped.
+ *
+ * @typeParam TQuery - The query document type (e.g. `typeof GET_ORDERS`).
+ * @typeParam TFieldName - Union of metadata field names (default: `string`,
+ *                         which disables metadata-aware checks).
+ */
+export type ValidateCollectionQuery<
+  TQuery,
+  TFieldName extends string = string,
+  TOrderableFieldName extends string = TFieldName,
+> =
+  ExtractQueryVariables<TQuery> extends never
+    ? TQuery // No gql-tada type info → skip validation
+    : string extends TFieldName
+      ? TQuery & CheckFirstVariable<TQuery> // No metadata → only check $first
+      : TQuery &
+          CheckFirstVariable<TQuery> &
+          CheckOrderField<TQuery, TOrderableFieldName> &
+          CheckQueryInput<TQuery, TFieldName>;
+
+/**
+ * Helper to check whether a `ValidateCollectionQuery` result contains any
+ * validation error.  Use this in type-level assertions instead of checking
+ * individual error keys.
+ */
+export type HasCollectionQueryError<T> = T extends
+  | { __firstVariableError: string }
+  | { __orderFieldError: string }
+  | { __queryInputError: string }
+  ? true
+  : false;
+
 /**
  * Find table names in metadata whose fields are a superset of `TFieldName`.
  *