fimo 0.4.0-experimental.1 → 0.4.0-experimental.3

package/assets/content-templates/hooks-template.eta

@@ -8,80 +8,21 @@
  */
 %>
 // AUTO-GENERATED ⚠️ – do not edit by hand
-import { useSuspenseQuery, useQuery, useMutation, useQueryClient, QueryKey } from "@tanstack/react-query";
-import { FimoString, FimoDate, FimoMedia, FimoBoolean, FimoRichText, useLocale, type Fields, type Projected, type Query, type Sort, type Where } from "fimo/ui";
+import { useSuspenseQuery, useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { FimoString, FimoMedia, FimoBoolean, FimoRichText, useLocale } from "fimo/ui";
 // @ts-ignore - virtual module provided by Fimo's Vite plugin
 import fimoConfig from "virtual:fimo-config";
-
-/*───────────────────────────────────────────────────────────────*/
-/*  ────────────  📄  Type definitions  ────────────             */
-/*───────────────────────────────────────────────────────────────*/
-
-/**
- * <%= model.pascal %> entity interface
- */
-export interface <%= model.pascal %>FimoMeta {
-  contentType: string;
-  translationProgress: { state: "queued" | "translating"; fields?: string[] } | null;
-}
-
-export interface <%= model.pascal %> {
-  id: string;
-  documentId: string;
-  slug: FimoString;
-  locale: string;
-  createdAt: string;
-  updatedAt: string;
-  __fimo: <%= model.pascal %>FimoMeta;
+import type { <%= model.pascal %>, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Result<% if (!model.isSingleton) { %>, <%= model.pascal %>Fields, <%= model.pascal %>Query<% } %> } from "./<%= model.pascal %>.types";
 <%
-// Generate interface properties based on fields
-if (model.fields) {
-  Object.entries(model.fields).forEach(([key, field]) => {
-    const type = getTypeForField(field);
+if (model.relationImports && model.relationImports.length > 0) {
+  model.relationImports.forEach((relationImport) => {
 -%>
-  <%= key %>: <%= type %>;
+import { wrapWithSource as wrap<%= relationImport.pascal %>WithSource } from "./<%= relationImport.pascal %>";
 <%
   });
 }
-
-/**
- * Helper function to convert schema field types to TypeScript types
- * Uses Fimo wrapper types for source tracking
- */
-function getTypeForField(field) {
-  switch(field.type) {
-    case 'string':
-      return 'FimoString';
-    case 'richtext':
-      return 'FimoRichText';
-    case 'number':
-      return 'number';
-    case 'boolean':
-      return 'FimoBoolean';
-    case 'date':
-      return 'string';
-    case 'json':
-      return 'Record<string, any>';
-    case 'media':
-      return field.multiple ? 'FimoMedia[]' : 'FimoMedia';
-    case 'relation':
-      return field.many ? 'Array<string | Record<string, any>>' : 'string | Record<string, any> | null';
-    default:
-      return 'any';
-  }
-}
 -%>
-}
-
-/*───────────────────────────────────────────────────────────────*/
-/*  ────────────  🔎  Query types  ────────────                  */
-/*───────────────────────────────────────────────────────────────*/
-
-export type <%= model.pascal %>Where = Where<<%= model.pascal %>>;
-export type <%= model.pascal %>Sort = Sort<<%= model.pascal %>>;
-export type <%= model.pascal %>Fields = Fields<<%= model.pascal %>>;
-export type <%= model.pascal %>Query<TFields extends <%= model.pascal %>Fields | undefined = <%= model.pascal %>Fields | undefined> = Query<<%= model.pascal %>, TFields>;
-export type <%= model.pascal %>Result<TFields extends <%= model.pascal %>Fields | undefined = undefined> = Projected<<%= model.pascal %>, TFields>;
+export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %>FimoMeta, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Query, <%= model.pascal %>Relations, <%= model.pascal %>Result, <%= model.pascal %>Sort, <%= model.pascal %>Where } from "./<%= model.pascal %>.types";
 
 /*───────────────────────────────────────────────────────────────*/
 /*  ────────────  🎁  Source wrapping  ────────────              */
@@ -90,7 +31,7 @@ export type <%= model.pascal %>Result<TFields extends <%= model.pascal %>Fields
 /**
  * Wraps raw API data with Fimo types for source tracking
  */
-function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
+export function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
   const id = entry.id;
   const sourcePrefix = `<%= model.pascal %>.${id}`;
   const entryFimo = entry.__fimo && typeof entry.__fimo === "object" ? entry.__fimo : {};
@@ -99,12 +40,13 @@ function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
     id,
     documentId: entry.documentId,
     slug: entry.slug != null ? new FimoString(entry.slug, `${sourcePrefix}.slug`) : entry.slug,
+<% if (model.localized) { -%>
     locale: entry.locale,
+<% } -%>
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
     __fimo: {
       contentType: typeof entryFimo.contentType === "string" ? entryFimo.contentType : "<%= model.uid %>",
-      translationProgress: entryFimo.translationProgress && typeof entryFimo.translationProgress === "object" ? entryFimo.translationProgress as <%= model.pascal %>FimoMeta["translationProgress"] : null,
     },
 <%
 if (model.fields) {
@@ -137,6 +79,19 @@ if (model.fields) {
 <%
         }
         break;
+      case 'relation': {
+        const wrapper = field.target === model.uid ? 'wrapWithSource' : `wrap${field.targetPascal}WithSource`;
+        if (field.many) {
+-%>
+    <%= key %>: Array.isArray(entry.<%= key %>) ? entry.<%= key %>.map((value: any) => value != null && typeof value === "object" && typeof value.id === "string" ? <%= wrapper %>(value) : value) : entry.<%= key %>,
+<%
+        } else {
+-%>
+    <%= key %>: entry.<%= key %> != null && typeof entry.<%= key %> === "object" && typeof entry.<%= key %>.id === "string" ? <%= wrapper %>(entry.<%= key %>) : entry.<%= key %>,
+<%
+        }
+        break;
+      }
       default:
 -%>
     <%= key %>: entry.<%= key %>,
@@ -159,7 +114,25 @@ function defaultLocale(): string {
 }
 
 function useQueryLocale(locale?: string): string {
-  return locale ?? useLocale().locale ?? defaultLocale();
+  const activeLocale = useLocale().locale;
+  return locale ?? activeLocale ?? defaultLocale();
+}
+
+const LOCALIZED_CONTENT = <%= model.localized ? 'true' : 'false' %>;
+const LOCALIZED_RELATION_FIELDS = new Set<string>(<%= JSON.stringify(model.localizedRelationFields) %>);
+
+function populateFields(populate: <%= model.pascal %>Populate | undefined): string[] {
+  if (populate == null) return [];
+  return typeof populate === "string" ? [populate] : [...populate];
+}
+
+function readLocale(
+  options: { locale?: string; populate?: <%= model.pascal %>Populate },
+  ownerUsesLocale: boolean,
+  fallbackLocale = defaultLocale()
+): string | undefined {
+  const populatesLocalizedTarget = populateFields(options.populate).some((field) => LOCALIZED_RELATION_FIELDS.has(field));
+  return ownerUsesLocale || populatesLocalizedTarget ? options.locale ?? fallbackLocale : undefined;
 }
 
 function fimoHeaders(extra?: Record<string, string>): Record<string, string> {
@@ -170,13 +143,21 @@ function fimoHeaders(extra?: Record<string, string>): Record<string, string> {
   return h;
 }
 
-function withLocale(url: string, locale?: string): string {
+function withReadOptions<TPopulate extends <%= model.pascal %>Populate | undefined>(
+  url: string,
+  options: { locale?: string; populate?: TPopulate } = {},
+  ownerUsesLocale = LOCALIZED_CONTENT
+): string {
   const u = new URL(url, "http://fimo.local");
-  u.searchParams.set("locale", locale ?? defaultLocale());
+  const locale = readLocale(options, ownerUsesLocale);
+  if (locale) u.searchParams.set("locale", locale);
+  if (options.populate != null) {
+    u.searchParams.set("populate", typeof options.populate === "string" ? options.populate : options.populate.join(","));
+  }
   return `${u.pathname}${u.search}`;
 }
 
-function splitWritePayload(payload: Partial<<%= model.pascal %>>): Record<string, unknown> {
+function splitWritePayload(payload: Partial<<%= model.pascal %>Input>): Record<string, unknown> {
   const {
     id,
     documentId,
@@ -194,31 +175,45 @@ function splitWritePayload(payload: Partial<<%= model.pascal %>>): Record<string
   };
 }
 
-export async function getById(id: string, options: { locale?: string } = {}): Promise<<%= model.pascal %>> {
-  const res = await fetch(`${base}${withLocale(`/entries/<%= model.uid %>/${id}`, options.locale)}`, { headers: fimoHeaders() });
+<% if (!model.isSingleton) { -%>
+export async function getById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
+  id: string,
+  options: { locale?: string; populate?: TPopulate } = {}
+): Promise<<%= model.pascal %>Result<undefined, TPopulate>> {
+  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/${id}`, options, false)}`, { headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
-  return wrapWithSource(data.data);
+  return wrapWithSource(data.data) as <%= model.pascal %>Result<undefined, TPopulate>;
 }
 
-export async function getBySlug(slug: string, options: { locale?: string } = {}): Promise<<%= model.pascal %> | null> {
-  const res = await fetch(`${base}${withLocale(`/entries/<%= model.uid %>/slug/${encodeURIComponent(slug)}`, options.locale)}`, { headers: fimoHeaders() });
+export async function getBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
+  slug: string,
+  options: { locale?: string; populate?: TPopulate } = {}
+): Promise<<%= model.pascal %>Result<undefined, TPopulate> | null> {
+  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/slug/${encodeURIComponent(slug)}`, options)}`, { headers: fimoHeaders() });
   if (res.status === 404) return null;
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
-  return wrapWithSource(data.data);
+  return wrapWithSource(data.data) as <%= model.pascal %>Result<undefined, TPopulate>;
 }
 
-export async function getByField(fieldName: string, value: string, options: { locale?: string } = {}): Promise<<%= model.pascal %> | null> {
-  const res = await fetch(`${base}${withLocale(`/entries/<%= model.uid %>/field/${encodeURIComponent(fieldName)}/${encodeURIComponent(value)}`, options.locale)}`, { headers: fimoHeaders() });
+export async function getByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
+  fieldName: string,
+  value: string,
+  options: { locale?: string; populate?: TPopulate } = {}
+): Promise<<%= model.pascal %>Result<undefined, TPopulate> | null> {
+  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/field/${encodeURIComponent(fieldName)}/${encodeURIComponent(value)}`, options)}`, { headers: fimoHeaders() });
   if (res.status === 404) return null;
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
-  return wrapWithSource(data.data);
+  return wrapWithSource(data.data) as <%= model.pascal %>Result<undefined, TPopulate>;
 }
 
-function toQueryString<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>): string {
-  const { where, sort, fields, populate, ...flat } = params;
+function toQueryString<
+  TFields extends <%= model.pascal %>Fields | undefined = undefined,
+  TPopulate extends <%= model.pascal %>Populate | undefined = undefined,
+>(params: <%= model.pascal %>Query<TFields, TPopulate> = {} as <%= model.pascal %>Query<TFields, TPopulate>): string {
+  const { where, sort, fields, populate, locale: requestedLocale, ...flat } = params;
   const query = new URLSearchParams();
 
   for (const [key, value] of Object.entries(flat)) {
@@ -242,22 +237,24 @@ function toQueryString<TFields extends <%= model.pascal %>Fields | undefined = u
     query.set("where", JSON.stringify(where));
   }
 
-  if (!query.has("locale")) {
-    query.set("locale", defaultLocale());
-  }
+  const locale = readLocale({ locale: requestedLocale, populate }, LOCALIZED_CONTENT);
+  if (locale) query.set("locale", locale);
 
   return query.toString();
 }
 
-export async function get<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>): Promise<<%= model.pascal %>Result<TFields>[]> {
+export async function get<
+  TFields extends <%= model.pascal %>Fields | undefined = undefined,
+  TPopulate extends <%= model.pascal %>Populate | undefined = undefined,
+>(params: <%= model.pascal %>Query<TFields, TPopulate> = {} as <%= model.pascal %>Query<TFields, TPopulate>): Promise<<%= model.pascal %>Result<TFields, TPopulate>[]> {
   const qs = toQueryString(params);
   const res = await fetch(`${base}/entries/<%= model.uid %>${qs ? "?" + qs : ""}`, { headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
-  return data.data.map(wrapWithSource) as <%= model.pascal %>Result<TFields>[];
+  return data.data.map(wrapWithSource) as <%= model.pascal %>Result<TFields, TPopulate>[];
 }
 
-export async function create(payload: Partial<<%= model.pascal %>>): Promise<<%= model.pascal %>> {
+export async function create(payload: <%= model.pascal %>Input): Promise<<%= model.pascal %>> {
   const res = await fetch(`${base}/entries/<%= model.uid %>`, {
     method: "POST",
     headers: fimoHeaders({ "Content-Type": "application/json" }),
@@ -265,10 +262,10 @@ export async function create(payload: Partial<<%= model.pascal %>>): Promise<<%=
   });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
-  return data.data;
+  return wrapWithSource(data.data);
 }
 
-export async function update(id: string, payload: Partial<<%= model.pascal %>>): Promise<<%= model.pascal %>> {
+export async function update(id: string, payload: Partial<<%= model.pascal %>Input>): Promise<<%= model.pascal %>> {
   const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, {
     method: "PUT",
     headers: fimoHeaders({ "Content-Type": "application/json" }),
@@ -276,71 +273,107 @@ export async function update(id: string, payload: Partial<<%= model.pascal %>>):
   });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
-  return data.data;
+  return wrapWithSource(data.data);
 }
 
 export async function remove(id: string): Promise<void> {
   const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, { method: "DELETE", headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
 }
+<% } else { -%>
+export async function get<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
+  options: { locale?: string; populate?: TPopulate } = {}
+): Promise<<%= model.pascal %>Result<undefined, TPopulate>> {
+  const res = await fetch(`${base}${withReadOptions(`/documents/<%= model.uid %>`, options)}`, { headers: fimoHeaders() });
+  if (!res.ok) throw new Error(await res.text());
+  const data = await res.json();
+  return wrapWithSource(data.data) as <%= model.pascal %>Result<undefined, TPopulate>;
+}
+
+export async function update(payload: Partial<<%= model.pascal %>Input>): Promise<<%= model.pascal %>> {
+  const write = splitWritePayload(payload) as { data: Record<string, unknown>; locale?: string };
+  const url = withReadOptions(`/documents/<%= model.uid %>`, { locale: write.locale });
+  const res = await fetch(`${base}${url}`, {
+    method: "PUT",
+    headers: fimoHeaders({ "Content-Type": "application/json" }),
+    body: JSON.stringify({ data: write.data })
+  });
+  if (!res.ok) throw new Error(await res.text());
+  const data = await res.json();
+  return wrapWithSource(data.data);
+}
+<% } -%>
 
 /*───────────────────────────────────────────────────────────────*/
 /*  ────────────  🍯  React-Query hooks  ────────────            */
 /*───────────────────────────────────────────────────────────────*/
 
+<% if (!model.isSingleton) { -%>
 const qk = {
   root       : ["<%= model.pascal %>"] as const,
-  byId       : (id: string, locale?: string) => ["<%= model.pascal %>", id, locale ?? defaultLocale()] as const,
-  bySlug     : (slug: string, locale?: string) => ["<%= model.pascal %>", "slug", slug, locale ?? defaultLocale()] as const,
-  byField    : (field: string, value: string, locale?: string) => ["<%= model.pascal %>", field, value, locale ?? defaultLocale()] as const,
+  byId       : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate } = {}) => ["<%= model.pascal %>", id, options.locale, options.populate] as const,
+  bySlug     : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate } = {}) => ["<%= model.pascal %>", "slug", slug, options.locale, options.populate] as const,
+  byField    : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(field: string, value: string, options: { locale?: string; populate?: TPopulate } = {}) => ["<%= model.pascal %>", field, value, options.locale, options.populate] as const,
   list       : (params: <%= model.pascal %>Query) => ["<%= model.pascal %>", params] as const
 };
 
-export function useGetById(id: string, options: { locale?: string } = {}) {
-  const locale = useQueryLocale(options.locale);
-  return useQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id, locale), queryFn: () => getById(id, { ...options, locale }) });
+export function useGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, false, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byId(id, localizedOptions), queryFn: () => getById(id, localizedOptions) });
 }
 
-export function useGetBySlug(slug: string, options: { locale?: string } = {}) {
-  const locale = useQueryLocale(options.locale);
-  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug, locale), queryFn: () => getBySlug(slug, { ...options, locale }), enabled: !!slug });
+export function useGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.bySlug(slug, localizedOptions), queryFn: () => getBySlug(slug, localizedOptions), enabled: !!slug });
 }
 
-export function useGetByField(fieldName: string, value: string, options: { locale?: string } = {}) {
-  const locale = useQueryLocale(options.locale);
-  return useQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value, locale), queryFn: () => getByField(fieldName, value, { ...options, locale }), enabled: !!value });
+export function useGetByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(fieldName: string, value: string, options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.byField(fieldName, value, localizedOptions), queryFn: () => getByField(fieldName, value, localizedOptions), enabled: !!value });
 }
 
-export function useGet<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>) {
-  const locale = useQueryLocale(params.locale);
+export function useGet<
+  TFields extends <%= model.pascal %>Fields | undefined = undefined,
+  TPopulate extends <%= model.pascal %>Populate | undefined = undefined,
+>(params: <%= model.pascal %>Query<TFields, TPopulate> = {} as <%= model.pascal %>Query<TFields, TPopulate>) {
+  const locale = readLocale(params, LOCALIZED_CONTENT, useQueryLocale(params.locale));
   const localizedParams = { ...params, locale };
-  return useQuery<<%= model.pascal %>Result<TFields>[], Error>({ queryKey: qk.list(localizedParams), queryFn: () => get(localizedParams) });
+  return useQuery<<%= model.pascal %>Result<TFields, TPopulate>[], Error>({ queryKey: qk.list(localizedParams), queryFn: () => get(localizedParams) });
 }
 
-export function useSuspenseGetById(id: string, options: { locale?: string } = {}) {
-  const locale = useQueryLocale(options.locale);
-  return useSuspenseQuery<<%= model.pascal %>, Error>({ queryKey: qk.byId(id, locale), queryFn: () => getById(id, { ...options, locale }) });
+export function useSuspenseGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, false, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byId(id, localizedOptions), queryFn: () => getById(id, localizedOptions) });
 }
 
-export function useSuspenseGetBySlug(slug: string, options: { locale?: string } = {}) {
-  const locale = useQueryLocale(options.locale);
-  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.bySlug(slug, locale), queryFn: () => getBySlug(slug, { ...options, locale }) });
+export function useSuspenseGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.bySlug(slug, localizedOptions), queryFn: () => getBySlug(slug, localizedOptions) });
 }
 
-export function useSuspenseGetByField(fieldName: string, value: string, options: { locale?: string } = {}) {
-  const locale = useQueryLocale(options.locale);
-  return useSuspenseQuery<<%= model.pascal %> | null, Error>({ queryKey: qk.byField(fieldName, value, locale), queryFn: () => getByField(fieldName, value, { ...options, locale }) });
+export function useSuspenseGetByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(fieldName: string, value: string, options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.byField(fieldName, value, localizedOptions), queryFn: () => getByField(fieldName, value, localizedOptions) });
 }
 
-export function useSuspenseGet<TFields extends <%= model.pascal %>Fields | undefined = undefined>(params: <%= model.pascal %>Query<TFields> = {} as <%= model.pascal %>Query<TFields>) {
-  const locale = useQueryLocale(params.locale);
+export function useSuspenseGet<
+  TFields extends <%= model.pascal %>Fields | undefined = undefined,
+  TPopulate extends <%= model.pascal %>Populate | undefined = undefined,
+>(params: <%= model.pascal %>Query<TFields, TPopulate> = {} as <%= model.pascal %>Query<TFields, TPopulate>) {
+  const locale = readLocale(params, LOCALIZED_CONTENT, useQueryLocale(params.locale));
   const localizedParams = { ...params, locale };
-  return useSuspenseQuery<<%= model.pascal %>Result<TFields>[], Error>({ queryKey: qk.list(localizedParams), queryFn: () => get(localizedParams) });
+  return useSuspenseQuery<<%= model.pascal %>Result<TFields, TPopulate>[], Error>({ queryKey: qk.list(localizedParams), queryFn: () => get(localizedParams) });
 }
 
 export function useCreate() {
   const qc = useQueryClient();
-  return useMutation<<%= model.pascal %>, Error, Partial<<%= model.pascal %>>>({
+  return useMutation<<%= model.pascal %>, Error, <%= model.pascal %>Input>({
     mutationFn   : create,
     onSuccess    : () => qc.invalidateQueries({ queryKey: qk.root })
   });
@@ -348,9 +381,12 @@ export function useCreate() {
 
 export function useUpdate() {
   const qc = useQueryClient();
-  return useMutation<<%= model.pascal %>, Error, { id: string } & Partial<<%= model.pascal %>>>({
+  return useMutation<<%= model.pascal %>, Error, { id: string } & Partial<<%= model.pascal %>Input>>({
     mutationFn   : ({ id, ...patch }) => update(id, patch),
-    onSuccess    : (_data, vars) => qc.invalidateQueries({ queryKey: qk.byId(vars.id) })
+    onSuccess    : (_data, vars) => {
+      qc.invalidateQueries({ queryKey: qk.root });
+      qc.invalidateQueries({ queryKey: qk.byId(vars.id) });
+    }
   });
 }
 
@@ -360,16 +396,43 @@ export function useRemove() {
     mutationFn   : remove,
     onSuccess    : (_data, id) => {
       qc.invalidateQueries({ queryKey: qk.root });
-      qc.removeQueries({ queryKey: qk.byId(id) as unknown as QueryKey });
+      qc.removeQueries({ queryKey: ["<%= model.pascal %>", id], exact: false });
     }
   });
 }
+<% } else { -%>
+const qk = {
+  root: ["<%= model.pascal %>"] as const,
+  document: <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate } = {}) => ["<%= model.pascal %>", "document", options.locale, options.populate] as const
+};
+
+export function useGet<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.document(localizedOptions), queryFn: () => get(localizedOptions) });
+}
+
+export function useSuspenseGet<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate } = {}) {
+  const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
+  const localizedOptions = { ...options, locale };
+  return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.document(localizedOptions), queryFn: () => get(localizedOptions) });
+}
+
+export function useUpdate() {
+  const qc = useQueryClient();
+  return useMutation<<%= model.pascal %>, Error, Partial<<%= model.pascal %>Input>>({
+    mutationFn: update,
+    onSuccess: () => qc.invalidateQueries({ queryKey: qk.root })
+  });
+}
+<% } -%>
 
 /*───────────────────────────────────────────────────────────────*/
 /*  ────────────  🎯  Default export  ────────────               */
 /*───────────────────────────────────────────────────────────────*/
 
 export default {
+<% if (!model.isSingleton) { -%>
   /* async helpers */
   getById,
   getBySlug,
@@ -391,4 +454,11 @@ export default {
   useCreate,
   useUpdate,
   useRemove
+<% } else { -%>
+  get,
+  update,
+  useGet,
+  useSuspenseGet,
+  useUpdate
+<% } -%>
 };

package/assets/content-templates/types-template.eta

@@ -0,0 +1,162 @@
+<%
+/**
+ * INPUT  ▸  model = {
+ *            uid: "api::blog.blog",     // UID in format "api::name.name"
+ *            pascal: "Blog"             // PascalCase for type names
+ *            fields: {key: {type, required?, multiple?}} // Schema fields
+ *          }
+ */
+%>
+// AUTO-GENERATED ⚠️ – do not edit by hand
+import { type Fields, type FimoBoolean, type FimoMedia, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithRelations } from "fimo/ui";
+<%
+if (model.relationImports && model.relationImports.length > 0) {
+  model.relationImports.forEach((relationImport) => {
+-%>
+import type { <%= relationImport.pascal %> } from "./<%= relationImport.pascal %>.types";
+<%
+  });
+}
+-%>
+
+/*───────────────────────────────────────────────────────────────*/
+/*  ────────────  📄  Type definitions  ────────────             */
+/*───────────────────────────────────────────────────────────────*/
+
+/**
+ * <%= model.pascal %> entity interface
+ */
+export interface <%= model.pascal %>FimoMeta {
+  contentType: string;
+}
+
+export interface <%= model.pascal %> extends WithRelations<<%= model.pascal %>Relations> {
+  id: string;
+  documentId: string;
+  slug: FimoString;
+<% if (model.localized) { -%>
+  locale: string;
+<% } -%>
+  createdAt: string;
+  updatedAt: string;
+  __fimo: <%= model.pascal %>FimoMeta;
+<%
+// Generate interface properties based on fields
+if (model.fields) {
+  Object.entries(model.fields).forEach(([key, field]) => {
+    const type = getTypeForField(field);
+-%>
+  <%= key %>: <%= type %>;
+<%
+  });
+}
+-%>
+
+export interface <%= model.pascal %>Input {
+  slug?: string;
+<% if (model.localized) { -%>
+  locale?: string;
+<% } -%>
+<% if (!model.isSingleton) { -%>
+  documentId?: string;
+<% } -%>
+<%
+if (model.fields) {
+  Object.entries(model.fields).forEach(([key, field]) => {
+    const type = getInputTypeForField(field);
+-%>
+  <%= key %><%= field.required ? '' : '?' %>: <%= type %>;
+<%
+  });
+}
+-%>
+}
+
+<%
+/**
+ * Helper function to convert schema field types to TypeScript types
+ * Uses Fimo wrapper types for source tracking
+ */
+function getTypeForField(field) {
+  switch(field.type) {
+    case 'string':
+      return 'FimoString';
+    case 'richtext':
+      return 'FimoRichText';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'FimoBoolean';
+    case 'date':
+      return 'string';
+    case 'json':
+      return 'Record<string, any>';
+    case 'media':
+      return field.multiple ? 'FimoMedia[]' : 'FimoMedia';
+    case 'relation':
+      return field.many ? 'FimoReference[]' : 'FimoReference | null';
+    default:
+      return 'any';
+  }
+}
+
+function getInputTypeForField(field) {
+  switch(field.type) {
+    case 'string':
+      return 'string';
+    case 'richtext':
+      return 'FimoRichTextContent';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'date':
+      return 'string';
+    case 'json':
+      return 'Record<string, unknown>';
+    case 'media': {
+      const media = 'Pick<FimoMedia, "url" | "alt" | "name" | "mime" | "width" | "height">';
+      return field.multiple ? `${media}[]` : media;
+    }
+    case 'relation':
+      return field.many ? 'FimoReference[]' : 'FimoReference | null';
+    default:
+      return 'unknown';
+  }
+}
+-%>
+}
+
+export interface <%= model.pascal %>Relations {
+<%
+if (model.fields) {
+  Object.entries(model.fields).forEach(([key, field]) => {
+    if (field.type !== 'relation' || typeof field.targetPascal !== 'string') {
+      return;
+    }
+    const type = field.many ? `${field.targetPascal}[]` : `${field.targetPascal} | null`;
+-%>
+  <%= key %>: <%= type %>;
+<%
+  });
+}
+-%>
+}
+
+export type <%= model.pascal %>Populate = Populate<<%= model.pascal %>>;
+
+/*───────────────────────────────────────────────────────────────*/
+/*  ────────────  🔎  Query types  ────────────                  */
+/*───────────────────────────────────────────────────────────────*/
+
+export type <%= model.pascal %>Where = Where<<%= model.pascal %>>;
+export type <%= model.pascal %>Sort = Sort<<%= model.pascal %>>;
+export type <%= model.pascal %>Fields = Fields<<%= model.pascal %>>;
+export type <%= model.pascal %>Query<
+  TFields extends <%= model.pascal %>Fields | undefined = <%= model.pascal %>Fields | undefined,
+  TPopulate extends <%= model.pascal %>Populate | undefined = <%= model.pascal %>Populate | undefined,
+> = Query<<%= model.pascal %>, TFields, TPopulate>;
+export type <%= model.pascal %>Result<
+  TFields extends <%= model.pascal %>Fields | undefined = undefined,
+  TPopulate extends <%= model.pascal %>Populate | undefined = undefined,
+> = ProjectedWithPopulate<PopulatedResult<<%= model.pascal %>, TPopulate>, TFields, TPopulate>;