@xleddyl/nuxt-cms 0.1.40 → 0.1.42

package/README.md

@@ -57,8 +57,9 @@ Then declare your content types in a `cms.config.ts` at the project root with `d
 ### Disabling the CMS
 
 Keep the module in `modules[]` at all times and turn it off with the `enabled` option or the
-`NUXT_CMS_ENABLED` env var. When disabled the module registers no-op `useCms` / `$cmsQuery` stubs and
-nothing else, so components can call them unconditionally and simply render their empty states:
+`NUXT_CMS_ENABLED` env var. When disabled the module registers no-op query composables and keeps the
+generated types, and nothing else, so components can call them unconditionally and simply render
+their empty states:
 
 ```ts
 export default defineNuxtConfig({
@@ -97,7 +98,7 @@ Full documentation lives in [`docs/`](docs/README.md):
 - [Configuration](docs/configuration.md) — every `cms.*` option and the `NUXT_CMS_*` env vars.
 - [Database](docs/database.md) — SQLite, Postgres, libSQL/Turso and D1 drivers, migrations, studio.
 - [Schema](docs/schema.md) — `defineCmsConfig`, entries, field types, relations, blocks, i18n.
-- [Querying content](docs/querying.md) — GraphQL API, `useCms` / `$cmsQuery`, filters, sorting, pagination.
+- [Querying content](docs/querying.md) — GraphQL API, `useCmsSingle` / `useCmsCollection` / `useCms` / `$cmsQuery`, filters, sorting, pagination.
 - [Admin panel & security](docs/admin.md) — pages, authentication, sessions, admin REST API.
 - [Media](docs/media.md) — S3-compatible storage or local mode backed by your `public/` folder, upload flow, allowed file types.
 - [Deployment](docs/deployment.md) — host/driver matrix, migrations on serverless, horizontal scaling, Cloudflare Workers.

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@xleddyl/nuxt-cms",
   "configKey": "cms",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -3,14 +3,14 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, isAbsolute, resolve, relative, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { defineNuxtModule, createResolver, useLogger, addImports, resolvePath, addTemplate, addServerPlugin, addTypeTemplate, addVitePlugin, addComponentsDir, addRouteMiddleware, extendPages, addServerHandler } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, useLogger, addImports, addTemplate, addServerPlugin, addTypeTemplate, addVitePlugin, addComponentsDir, addRouteMiddleware, extendPages, addServerHandler, resolvePath } from '@nuxt/kit';
 import tailwindcss from '@tailwindcss/vite';
 import svgLoader from 'vite-svg-loader';
 import { introspectionFromSchema, buildSchema } from 'graphql';
 import { minifyIntrospection, outputIntrospectionFile } from 'gql.tada/internal';
 import { createJiti } from 'jiti';
-import { typeName, blockTypeName, blockUnionName, renderGraphqlSdl } from '../dist/runtime/shared/graphql-sdl.js';
-import { isMultiSelect, fieldConditions, isTranslatableField, isTranslatableMediaField, isRequiredField, isPrivateField, DEFAULT_MEDIA_MAX_FILE_SIZE } from '../dist/runtime/shared/index.js';
+import { typeName, blockTypeName, blocksFieldTypeName, renderGraphqlSdl } from '../dist/runtime/shared/graphql-sdl.js';
+import { isTranslatableField, isTranslatableMediaField, isMultiSelect, fieldConditions, isRequiredField, isPrivateField, mediaTypeFilter, DEFAULT_MEDIA_MAX_FILE_SIZE } from '../dist/runtime/shared/index.js';
 import { scanMediaDirectory, readMediaFileMeta } from '../dist/runtime/server/utils/media-sync.js';
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
@@ -450,6 +450,84 @@ ${[mediaTableExpr(dialect), ...tables, ...joins].join(
 `;
 }
 
+const MEDIA_SELECTION = "key url type alt folder mime size width height";
+function blocksSelection(entryName, key, field) {
+  const parts = ["type"];
+  for (const [blockName, block] of Object.entries(field.blocks ?? {})) {
+    const fields = Object.entries(block.fields).map(
+      ([blockFieldKey, blockField]) => blockField.type === "media" ? `${blockFieldKey} { ${MEDIA_SELECTION} }` : blockFieldKey
+    );
+    if (!fields.length) continue;
+    parts.push(`... on ${blockTypeName(entryName, key, blockName)} { ${fields.join(" ")} }`);
+  }
+  return parts.join(" ");
+}
+function entrySelection(config, name, entry, withRelations) {
+  const parts = ["id"];
+  for (const [key, field] of Object.entries(entry.fields)) {
+    if (isPrivateField(field)) continue;
+    if (field.type === "relation") {
+      const target = config[field.to];
+      if (!withRelations || !target) continue;
+      parts.push(`${key} { ${entrySelection(config, field.to, target, false)} }`);
+      continue;
+    }
+    if (field.type === "media") {
+      parts.push(`${key} { ${MEDIA_SELECTION} }`);
+      continue;
+    }
+    if (field.type === "blocks") {
+      parts.push(`${key} { ${blocksSelection(name, key, field)} }`);
+      continue;
+    }
+    parts.push(key);
+  }
+  if (entry.kind === "collection") parts.push("createdAt");
+  parts.push("updatedAt");
+  return parts.join(" ");
+}
+function singleQuery(config, name, entry) {
+  const selection = entrySelection(config, name, entry, true);
+  return `query CmsSingle($locale: String) { ${name}(locale: $locale) { ${selection} } }`;
+}
+function collectionQuery(config, name, entry) {
+  const selection = entrySelection(config, name, entry, true);
+  const gqlType = typeName(name);
+  const args = [
+    "$locale: String",
+    `$filters: ${gqlType}Filters`,
+    `$sort: [${gqlType}Sort!]`,
+    "$limit: Int",
+    "$offset: Int"
+  ].join(", ");
+  return `query CmsCollection(${args}) { ${name}(locale: $locale, filters: $filters, sort: $sort, limit: $limit, offset: $offset) { ${selection} } }`;
+}
+function renderQueriesFile(config) {
+  const singles = [];
+  const collections = [];
+  for (const [name, entry] of Object.entries(config)) {
+    const line = `   ${JSON.stringify(name)}: ${JSON.stringify(
+      entry.kind === "single" ? singleQuery(config, name, entry) : collectionQuery(config, name, entry)
+    )},`;
+    if (entry.kind === "single") singles.push(line);
+    else collections.push(line);
+  }
+  return [
+    `export const cmsSingleQueries: Record<string, string> = {`,
+    ...singles,
+    `}`,
+    ``,
+    `export const cmsCollectionQueries: Record<string, string> = {`,
+    ...collections,
+    `}`,
+    ``
+  ].join("\n");
+}
+
+function mediaTsType(field) {
+  const types = mediaTypeFilter(field.mediaType);
+  return types ? `CmsMedia<${types.map((type) => `'${type}'`).join(" | ")}>` : "CmsMedia";
+}
 function scalarTsType(field) {
   switch (field.type) {
     case "number":
@@ -470,13 +548,13 @@ function fieldTsType(config, entryName, key, field) {
     if (field.cardinality === "many-to-many") return `${target}[]`;
     return isRequiredField(field) && !config[field.to]?.drafts ? target : `${target} | null`;
   }
-  if (field.type === "media") return "CmsMedia | null";
+  if (field.type === "media") return `${mediaTsType(field)} | null`;
   if (field.type === "select" && field.multiple) {
     const union = field.options.map((o) => JSON.stringify(o)).join(" | ");
     return `(${union})[]`;
   }
   if (field.type === "blocks") {
-    const union = blockUnionName(entryName, key);
+    const union = blocksFieldTypeName(entryName, key);
     return isRequiredField(field) ? `${union}[]` : `${union}[] | null`;
   }
   if (isTranslatableField(field)) return isRequiredField(field) ? "string" : "string | null";
@@ -492,7 +570,7 @@ function blockTypesTs(entryName, key, field) {
     const lines = [`  __typename?: '${name}'`, `  type: '${blockName}'`];
     for (const [blockFieldKey, blockField] of Object.entries(block.fields)) {
       if (blockField.type === "media") {
-        lines.push(`  ${blockFieldKey}: CmsMedia | null`);
+        lines.push(`  ${blockFieldKey}: ${mediaTsType(blockField)} | null`);
         continue;
       }
       const base = scalarTsType(blockField);
@@ -503,7 +581,7 @@ ${lines.join("\n")}
 }`);
   }
   if (members.length)
-    defs.push(`export type ${blockUnionName(entryName, key)} = ${members.join(" | ")}`);
+    defs.push(`export type ${blocksFieldTypeName(entryName, key)} = ${members.join(" | ")}`);
   return defs;
 }
 function entryTs(config, name, entry) {
@@ -518,12 +596,61 @@ function entryTs(config, name, entry) {
 ${lines.join("\n")}
 }`;
 }
+function relationKeys(entry) {
+  return Object.entries(entry.fields).filter(([, field]) => field.type === "relation" && !isPrivateField(field)).map(([key]) => key);
+}
+function quotedKeys(keys) {
+  return keys.map((key) => `'${key}'`).join(" | ");
+}
+function shallowTypeTs(config, name) {
+  const target = typeName(name);
+  const entry = config[name];
+  const keys = entry ? relationKeys(entry) : [];
+  return keys.length ? `Omit<${target}, ${quotedKeys(keys)}>` : target;
+}
+function autoTypeTs(config, name, entry) {
+  const auto = `${typeName(name)}Auto`;
+  const keys = relationKeys(entry);
+  if (!keys.length) return `export type ${auto} = ${typeName(name)}`;
+  const lines = keys.map((key) => {
+    const field = entry.fields[key];
+    const shallow = shallowTypeTs(config, field.to);
+    if (field.cardinality === "many-to-many") return `  ${key}: ${shallow}[]`;
+    const nonNull = isRequiredField(field) && !config[field.to]?.drafts;
+    return `  ${key}: ${shallow}${nonNull ? "" : " | null"}`;
+  });
+  return `export type ${auto} = Omit<${typeName(name)}, ${quotedKeys(keys)}> & {
+${lines.join(
+    "\n"
+  )}
+}`;
+}
+function entryMapsTs(config) {
+  const singles = [];
+  const collections = [];
+  for (const [name, entry] of Object.entries(config)) {
+    const line = `  ${JSON.stringify(name)}: ${typeName(name)}Auto`;
+    if (entry.kind === "single") singles.push(line);
+    else collections.push(line);
+  }
+  return [
+    `export interface CmsSingleTypes {
+${singles.join("\n")}
+}`,
+    `export interface CmsCollectionTypes {
+${collections.join("\n")}
+}`,
+    `export type CmsSingleName = keyof CmsSingleTypes`,
+    `export type CmsCollectionName = keyof CmsCollectionTypes`
+  ];
+}
 function renderTypesFile(config) {
   const parts = [
-    `export interface CmsMedia {
+    `export type CmsMediaType = 'image' | 'video' | 'file'`,
+    `export interface CmsMedia<T extends CmsMediaType = CmsMediaType> {
   key: string
   url: string | null
-  type: 'image' | 'video' | 'file'
+  type: T
   alt: string | null
   folder: string | null
   mime: string | null
@@ -539,6 +666,8 @@ function renderTypesFile(config) {
     }
     parts.push(entryTs(config, name, entry));
   }
+  for (const [name, entry] of Object.entries(config)) parts.push(autoTypeTs(config, name, entry));
+  parts.push(...entryMapsTs(config));
   return `${parts.join("\n\n")}
 `;
 }
@@ -627,6 +756,104 @@ function resolveModuleOptions(options) {
     }
   };
 }
+const moduleRequire = createRequire(import.meta.url);
+function resolveImport(specifier) {
+  try {
+    return fileURLToPath(import.meta.resolve(specifier)).replace(/\\/g, "/");
+  } catch {
+    return moduleRequire.resolve(specifier).replace(/\\/g, "/");
+  }
+}
+async function loadCmsConfig(nuxt, resolver, configPathOption, i18n, logger) {
+  const configPath = await resolvePath(configPathOption, { cwd: nuxt.options.rootDir });
+  nuxt.options.alias["#nuxt-cms"] = resolver.resolve("./runtime/shared/index");
+  nuxt.options.watch.push(configPath);
+  let cmsConfig = {};
+  if (existsSync(configPath)) {
+    nuxt.options.alias["#cms-config"] = configPath;
+    const jiti = createJiti(import.meta.url, {
+      moduleCache: false,
+      alias: { "#nuxt-cms": resolver.resolve("./runtime/shared/index") }
+    });
+    cmsConfig = await jiti.import(configPath, { default: true });
+  } else {
+    logger.warn(
+      `[nuxt-cms] Config file not found: ${configPath}. Using an empty registry \u2014 create a ${configPathOption}.ts with defineCmsConfig().`
+    );
+    nuxt.options.alias["#cms-config"] = resolver.resolve("./runtime/shared/empty-config");
+  }
+  const configErrors = validateConfig(cmsConfig, i18n);
+  if (configErrors.length) {
+    for (const error of configErrors) logger.error(error);
+    throw new Error(
+      `[nuxt-cms] Invalid cms config (${configErrors.length} error${configErrors.length > 1 ? "s" : ""})`
+    );
+  }
+  return cmsConfig;
+}
+function addCmsTypeTemplates(nuxt, cmsConfig) {
+  addTemplate({
+    filename: "cms/schema.graphql",
+    write: true,
+    getContents: () => renderGraphqlSdl(cmsConfig)
+  });
+  const typesTemplate = addTemplate({
+    filename: "cms/types.ts",
+    write: true,
+    getContents: () => renderTypesFile(cmsConfig)
+  });
+  nuxt.options.alias["#cms-types"] = typesTemplate.dst;
+  const queriesTemplate = addTemplate({
+    filename: "cms/queries.ts",
+    write: true,
+    getContents: () => renderQueriesFile(cmsConfig)
+  });
+  nuxt.options.alias["#cms-queries"] = queriesTemplate.dst;
+  addTemplate({
+    filename: "cms/graphql-env.d.ts",
+    write: true,
+    getContents: () => {
+      const introspection = minifyIntrospection(
+        introspectionFromSchema(buildSchema(renderGraphqlSdl(cmsConfig)))
+      );
+      return outputIntrospectionFile(introspection, {
+        fileType: ".d.ts",
+        shouldPreprocess: true
+      }).split("import * as gqlTada from 'gql.tada';")[0];
+    }
+  });
+  const gqlTadaTypesPath = resolveImport("gql.tada").replace(/\.[mc]?js$/, "");
+  const graphqlTemplate = addTemplate({
+    filename: "cms/graphql.ts",
+    write: true,
+    getContents: () => [
+      `import type { initGraphQLTada, ResultOf, VariablesOf } from '${gqlTadaTypesPath}'`,
+      `import type { introspection } from './graphql-env'`,
+      ``,
+      `export type CmsGraphql = initGraphQLTada<{`,
+      `  introspection: introspection`,
+      `  scalars: {`,
+      `    JSON: unknown`,
+      `  }`,
+      `}>`,
+      ``,
+      `declare const graphql: CmsGraphql`,
+      ``,
+      `// @ts-ignore: gql.tada's cache overload rejects this instantiation, but the parse overload still resolves`,
+      `export type CmsDocument<Query extends string> = ReturnType<typeof graphql<Query, []>>`,
+      ``,
+      `export type CmsResult<Query extends string> = string extends Query`,
+      `  ? Record<string, unknown>`,
+      `  : ResultOf<CmsDocument<Query>>`,
+      ``,
+      `export type CmsVariables<Query extends string> = string extends Query`,
+      `  ? Record<string, unknown>`,
+      `  : VariablesOf<CmsDocument<Query>>`,
+      ``
+    ].join("\n")
+  });
+  nuxt.options.alias["#cms-graphql"] = graphqlTemplate.dst;
+}
 const module$1 = defineNuxtModule({
   meta: {
     name: "@xleddyl/nuxt-cms",
@@ -671,11 +898,18 @@ const module$1 = defineNuxtModule({
     const logger = useLogger("nuxt-cms");
     const resolved = resolveModuleOptions(options);
     if (!resolveCmsEnabled(options.enabled, process.env[CMS_ENABLED_ENV])) {
-      const stub = resolver.resolve("./runtime/app/composables/cms-query-disabled");
+      const queryStub = resolver.resolve("./runtime/app/composables/cms-query-disabled");
+      const entryStub = resolver.resolve("./runtime/app/composables/cms-entry-disabled");
       addImports([
-        { name: "useCms", from: stub },
-        { name: "$cmsQuery", from: stub }
+        { name: "useCms", from: queryStub },
+        { name: "$cmsQuery", from: queryStub },
+        { name: "useCmsSingle", from: entryStub },
+        { name: "useCmsCollection", from: entryStub }
       ]);
+      addCmsTypeTemplates(
+        nuxt,
+        await loadCmsConfig(nuxt, resolver, resolved.configPath, resolved.i18n, logger)
+      );
       nuxt.options.runtimeConfig.public.cms = {
         mediaBaseUrl: resolved.media.publicBaseUrl,
         mediaStorage: resolved.media.storage,
@@ -683,7 +917,7 @@ const module$1 = defineNuxtModule({
         i18n: resolved.i18n
       };
       logger.info(
-        "[nuxt-cms] disabled: registering no-op useCms/$cmsQuery stubs, skipping admin, server and database setup"
+        "[nuxt-cms] disabled: registering no-op query composables and generated types, skipping admin, server and database setup"
       );
       return;
     }
@@ -708,38 +942,13 @@ const module$1 = defineNuxtModule({
         "[nuxt-cms] media.storage is 's3' with credentials configured but no publicBaseUrl (media.publicBaseUrl or NUXT_PUBLIC_CMS_MEDIA_BASE_URL); uploaded media URLs will be null."
       );
     }
-    const configPath = await resolvePath(resolved.configPath, { cwd: nuxt.options.rootDir });
-    nuxt.options.alias["#nuxt-cms"] = resolver.resolve("./runtime/shared/index");
-    nuxt.options.watch.push(configPath);
-    let cmsConfig = {};
-    if (existsSync(configPath)) {
-      nuxt.options.alias["#cms-config"] = configPath;
-      const jiti = createJiti(import.meta.url, {
-        moduleCache: false,
-        alias: { "#nuxt-cms": resolver.resolve("./runtime/shared/index") }
-      });
-      cmsConfig = await jiti.import(configPath, { default: true });
-    } else {
-      logger.warn(
-        `[nuxt-cms] Config file not found: ${configPath}. Using an empty registry \u2014 create a ${resolved.configPath}.ts with defineCmsConfig().`
-      );
-      nuxt.options.alias["#cms-config"] = resolver.resolve("./runtime/shared/empty-config");
-    }
-    const configErrors = validateConfig(cmsConfig, resolved.i18n);
-    if (configErrors.length) {
-      for (const error of configErrors) logger.error(error);
-      throw new Error(
-        `[nuxt-cms] Invalid cms config (${configErrors.length} error${configErrors.length > 1 ? "s" : ""})`
-      );
-    }
-    const moduleRequire = createRequire(import.meta.url);
-    const resolveImport = (specifier) => {
-      try {
-        return fileURLToPath(import.meta.resolve(specifier)).replace(/\\/g, "/");
-      } catch {
-        return moduleRequire.resolve(specifier).replace(/\\/g, "/");
-      }
-    };
+    const cmsConfig = await loadCmsConfig(
+      nuxt,
+      resolver,
+      resolved.configPath,
+      resolved.i18n,
+      logger
+    );
     const schemaTemplate = addTemplate({
       filename: "cms/schema.ts",
       write: true,
@@ -750,64 +959,14 @@ const module$1 = defineNuxtModule({
       )
     });
     nuxt.options.alias["#cms-tables"] = schemaTemplate.dst;
-    addTemplate({
-      filename: "cms/schema.graphql",
-      write: true,
-      getContents: () => renderGraphqlSdl(cmsConfig)
-    });
-    const typesTemplate = addTemplate({
-      filename: "cms/types.ts",
-      write: true,
-      getContents: () => renderTypesFile(cmsConfig)
-    });
-    nuxt.options.alias["#cms-types"] = typesTemplate.dst;
-    addTemplate({
-      filename: "cms/graphql-env.d.ts",
-      write: true,
-      getContents: () => {
-        const introspection = minifyIntrospection(
-          introspectionFromSchema(buildSchema(renderGraphqlSdl(cmsConfig)))
-        );
-        return outputIntrospectionFile(introspection, {
-          fileType: ".d.ts",
-          shouldPreprocess: true
-        }).split("import * as gqlTada from 'gql.tada';")[0];
-      }
-    });
-    const gqlTadaTypesPath = resolveImport("gql.tada").replace(/\.[mc]?js$/, "");
-    const graphqlTemplate = addTemplate({
-      filename: "cms/graphql.ts",
-      write: true,
-      getContents: () => [
-        `import type { initGraphQLTada, ResultOf, VariablesOf } from '${gqlTadaTypesPath}'`,
-        `import type { introspection } from './graphql-env'`,
-        ``,
-        `export type CmsGraphql = initGraphQLTada<{`,
-        `  introspection: introspection`,
-        `  scalars: {`,
-        `    JSON: unknown`,
-        `  }`,
-        `}>`,
-        ``,
-        `declare const graphql: CmsGraphql`,
-        ``,
-        `// @ts-ignore: gql.tada's cache overload rejects this instantiation, but the parse overload still resolves`,
-        `export type CmsDocument<Query extends string> = ReturnType<typeof graphql<Query, []>>`,
-        ``,
-        `export type CmsResult<Query extends string> = string extends Query`,
-        `  ? Record<string, unknown>`,
-        `  : ResultOf<CmsDocument<Query>>`,
-        ``,
-        `export type CmsVariables<Query extends string> = string extends Query`,
-        `  ? Record<string, unknown>`,
-        `  : VariablesOf<CmsDocument<Query>>`,
-        ``
-      ].join("\n")
-    });
-    nuxt.options.alias["#cms-graphql"] = graphqlTemplate.dst;
+    addCmsTypeTemplates(nuxt, cmsConfig);
+    const queryComposables = resolver.resolve("./runtime/app/composables/cms-query");
+    const entryComposables = resolver.resolve("./runtime/app/composables/cms-entry");
     addImports([
-      { name: "useCms", from: resolver.resolve("./runtime/app/composables/cms-query") },
-      { name: "$cmsQuery", from: resolver.resolve("./runtime/app/composables/cms-query") }
+      { name: "useCms", from: queryComposables },
+      { name: "$cmsQuery", from: queryComposables },
+      { name: "useCmsSingle", from: entryComposables },
+      { name: "useCmsCollection", from: entryComposables }
     ]);
     const {
       driver,

package/dist/runtime/app/composables/cms-entry-disabled.d.ts

@@ -0,0 +1,19 @@
+import type { AsyncData } from 'nuxt/app';
+import type { CmsCollectionName, CmsCollectionTypes, CmsSingleName, CmsSingleTypes } from '#cms-types';
+import type { CmsAsyncDataOptions } from './cms-query-disabled.js';
+export interface CmsSortInput<Entry> {
+    field: Extract<keyof Entry, string>;
+    direction?: 'asc' | 'desc';
+}
+export interface CmsSingleOptions<ResT, DefaultT> extends CmsAsyncDataOptions<ResT, DefaultT> {
+    locale?: string;
+}
+export interface CmsCollectionOptions<ResT, DefaultT, Entry> extends CmsAsyncDataOptions<ResT, DefaultT> {
+    locale?: string;
+    filters?: Record<string, unknown>;
+    sort?: CmsSortInput<Entry>[];
+    limit?: number;
+    offset?: number;
+}
+export declare function useCmsSingle<K extends CmsSingleName, DefaultT = null>(name: K, options?: CmsSingleOptions<CmsSingleTypes[K] | null, DefaultT>): AsyncData<CmsSingleTypes[K] | DefaultT | null, Error | undefined>;
+export declare function useCmsCollection<K extends CmsCollectionName, DefaultT = CmsCollectionTypes[K][]>(name: K, options?: CmsCollectionOptions<CmsCollectionTypes[K][], DefaultT, CmsCollectionTypes[K]>): AsyncData<CmsCollectionTypes[K][] | DefaultT, Error | undefined>;

package/dist/runtime/app/composables/cms-entry-disabled.js

@@ -0,0 +1,16 @@
+import { useAsyncData } from "#imports";
+export function useCmsSingle(name, options = {}) {
+  const { locale, key, default: fallback } = options;
+  return useAsyncData(
+    key ?? `cms-single:${String(name)}:${locale ?? ""}`,
+    async () => fallback ? fallback() : null
+  );
+}
+export function useCmsCollection(name, options = {}) {
+  const { locale, filters, sort, limit, offset, key, default: fallback } = options;
+  const variables = { locale, filters, sort, limit, offset };
+  return useAsyncData(
+    key ?? `cms-collection:${String(name)}:${JSON.stringify(variables)}`,
+    async () => fallback ? fallback() : []
+  );
+}

package/dist/runtime/app/composables/cms-entry.d.ts

@@ -0,0 +1,19 @@
+import type { AsyncData } from 'nuxt/app';
+import type { CmsCollectionName, CmsCollectionTypes, CmsSingleName, CmsSingleTypes } from '#cms-types';
+import type { CmsAsyncDataOptions } from './cms-query.js';
+export interface CmsSortInput<Entry> {
+    field: Extract<keyof Entry, string>;
+    direction?: 'asc' | 'desc';
+}
+export interface CmsSingleOptions<ResT, DefaultT> extends CmsAsyncDataOptions<ResT, DefaultT> {
+    locale?: string;
+}
+export interface CmsCollectionOptions<ResT, DefaultT, Entry> extends CmsAsyncDataOptions<ResT, DefaultT> {
+    locale?: string;
+    filters?: Record<string, unknown>;
+    sort?: CmsSortInput<Entry>[];
+    limit?: number;
+    offset?: number;
+}
+export declare function useCmsSingle<K extends CmsSingleName, DefaultT = null>(name: K, options?: CmsSingleOptions<CmsSingleTypes[K] | null, DefaultT>): AsyncData<CmsSingleTypes[K] | DefaultT | null, Error | undefined>;
+export declare function useCmsCollection<K extends CmsCollectionName, DefaultT = CmsCollectionTypes[K][]>(name: K, options?: CmsCollectionOptions<CmsCollectionTypes[K][], DefaultT, CmsCollectionTypes[K]>): AsyncData<CmsCollectionTypes[K][] | DefaultT, Error | undefined>;

package/dist/runtime/app/composables/cms-entry.js

@@ -0,0 +1,50 @@
+import { cmsCollectionQueries, cmsSingleQueries } from "#cms-queries";
+import { useAsyncData } from "#imports";
+import { $cmsQuery } from "./cms-query.js";
+function unknownEntry(name) {
+  throw new Error(`[nuxt-cms] no generated query for "${name}"; check cms.config.ts`);
+}
+export function useCmsSingle(name, options = {}) {
+  const { locale, key, default: fallback, ...asyncDataOptions } = options;
+  const entryName = String(name);
+  const query = cmsSingleQueries[entryName];
+  return useAsyncData(
+    key ?? `cms-single:${entryName}:${locale ?? ""}`,
+    async () => {
+      if (!query) unknownEntry(entryName);
+      const result = await $cmsQuery(query, { locale });
+      return result?.[entryName] ?? null;
+    },
+    {
+      default: fallback ?? (() => null),
+      ...asyncDataOptions
+    }
+  );
+}
+export function useCmsCollection(name, options = {}) {
+  const {
+    locale,
+    filters,
+    sort,
+    limit,
+    offset,
+    key,
+    default: fallback,
+    ...asyncDataOptions
+  } = options;
+  const entryName = String(name);
+  const query = cmsCollectionQueries[entryName];
+  const variables = { locale, filters, sort, limit, offset };
+  return useAsyncData(
+    key ?? `cms-collection:${entryName}:${JSON.stringify(variables)}`,
+    async () => {
+      if (!query) unknownEntry(entryName);
+      const result = await $cmsQuery(query, variables);
+      return result?.[entryName] ?? [];
+    },
+    {
+      default: fallback ?? (() => []),
+      ...asyncDataOptions
+    }
+  );
+}

package/dist/runtime/app/composables/cms-query-disabled.d.ts

@@ -1,6 +1,11 @@
-import type { AsyncData } from 'nuxt/app';
+import type { AsyncData, AsyncDataOptions } from 'nuxt/app';
 type CmsDisabledResult = Record<string, any>;
 type CmsDisabledVariables = Record<string, any>;
+export interface CmsAsyncDataOptions<ResT, DefaultT> extends Pick<AsyncDataOptions<ResT>, 'server' | 'lazy' | 'immediate' | 'deep' | 'dedupe' | 'watch'> {
+    key?: string;
+    default?: () => DefaultT;
+}
+export declare function cmsQueryKey(query: string, variables?: unknown): string;
 export declare function $cmsQuery<const Q extends string>(query: Q, variables?: CmsDisabledVariables): Promise<CmsDisabledResult>;
-export declare function useCms<const Q extends string>(query: Q, variables?: CmsDisabledVariables): AsyncData<CmsDisabledResult | undefined, Error | undefined>;
+export declare function useCms<const Q extends string, DefaultT = undefined>(query: Q, variables?: CmsDisabledVariables, options?: CmsAsyncDataOptions<CmsDisabledResult, DefaultT>): AsyncData<CmsDisabledResult | DefaultT | undefined, Error | undefined>;
 export {};

package/dist/runtime/app/composables/cms-query-disabled.js

@@ -1,10 +1,14 @@
 import { useAsyncData } from "#imports";
+export function cmsQueryKey(query, variables) {
+  return `cms-gql:${query}:${JSON.stringify(variables ?? {})}`;
+}
 export async function $cmsQuery(query, variables) {
   return {};
 }
-export function useCms(query, variables) {
+export function useCms(query, variables, options = {}) {
+  const { key, default: defaultValue } = options;
   return useAsyncData(
-    `cms-gql:${query}:${JSON.stringify(variables ?? {})}`,
-    async () => null
+    key ?? cmsQueryKey(query, variables),
+    async () => defaultValue ? defaultValue() : null
   );
 }

package/dist/runtime/app/composables/cms-query.d.ts

@@ -1,4 +1,9 @@
 import type { CmsResult, CmsVariables } from '#cms-graphql';
-import type { AsyncData } from 'nuxt/app';
+import type { AsyncData, AsyncDataOptions } from 'nuxt/app';
+export interface CmsAsyncDataOptions<ResT, DefaultT> extends Pick<AsyncDataOptions<ResT>, 'server' | 'lazy' | 'immediate' | 'deep' | 'dedupe' | 'watch'> {
+    key?: string;
+    default?: () => DefaultT;
+}
+export declare function cmsQueryKey(query: string, variables?: unknown): string;
 export declare function $cmsQuery<const Q extends string>(query: Q, variables?: CmsVariables<Q>): Promise<CmsResult<Q>>;
-export declare function useCms<const Q extends string>(query: Q, variables?: CmsVariables<Q>): AsyncData<CmsResult<Q> | undefined, Error | undefined>;
+export declare function useCms<const Q extends string, DefaultT = undefined>(query: Q, variables?: CmsVariables<Q>, options?: CmsAsyncDataOptions<CmsResult<Q>, DefaultT>): AsyncData<CmsResult<Q> | DefaultT | undefined, Error | undefined>;

package/dist/runtime/app/composables/cms-query.js

@@ -1,5 +1,8 @@
 import { useAsyncData } from "#imports";
 const ENDPOINT = "/api/cms/graphql";
+export function cmsQueryKey(query, variables) {
+  return `cms-gql:${query}:${JSON.stringify(variables ?? {})}`;
+}
 export async function $cmsQuery(query, variables) {
   const res = await $fetch(ENDPOINT, {
     method: "POST",
@@ -10,9 +13,11 @@ export async function $cmsQuery(query, variables) {
   }
   return res.data;
 }
-export function useCms(query, variables) {
+export function useCms(query, variables, options = {}) {
+  const { key, ...asyncDataOptions } = options;
   return useAsyncData(
-    `cms-gql:${query}:${JSON.stringify(variables ?? {})}`,
-    () => $cmsQuery(query, variables)
+    key ?? cmsQueryKey(query, variables),
+    () => $cmsQuery(query, variables),
+    asyncDataOptions
   );
 }

package/dist/runtime/server/utils/graphql.js

@@ -30,7 +30,12 @@ import {
   pickTranslatedMedia,
   translatableFieldKeys
 } from "../../shared/index.js";
-import { blockTypeName, blockUnionName, renderGraphqlSdl, typeName } from "../../shared/graphql-sdl.js";
+import {
+  blockTypeName,
+  blocksFieldTypeName,
+  renderGraphqlSdl,
+  typeName
+} from "../../shared/graphql-sdl.js";
 import { useMediaIndex } from "./media-index.js";
 import { getContentI18n, resolveTable, tableColumns } from "./registry.js";
 const MAX_LIMIT = 100;
@@ -285,7 +290,7 @@ function entryResolvers(config, name, entry) {
 }
 function blockResolvers(name, key, field) {
   const resolvers = {};
-  resolvers[blockUnionName(name, key)] = {
+  resolvers[blocksFieldTypeName(name, key)] = {
     __resolveType: (value) => blockTypeName(name, key, String(value.type))
   };
   for (const [blockName, block] of Object.entries(field.blocks ?? {})) {

package/dist/runtime/shared/graphql-sdl.d.ts

@@ -1,5 +1,4 @@
 import type { CmsConfig } from './index.js';
-export declare function typeName(name: string): string;
-export declare function blockUnionName(entryName: string, fieldKey: string): string;
-export declare function blockTypeName(entryName: string, fieldKey: string, blockName: string): string;
+import { blockTypeName, blocksFieldTypeName, typeName } from './index.js';
+export { blockTypeName, blocksFieldTypeName, typeName };
 export declare function renderGraphqlSdl(config: CmsConfig): string;

package/dist/runtime/shared/graphql-sdl.js

@@ -1,13 +1,12 @@
-import { isPrivateField, isRequiredField, isTranslatableField } from "./index.js";
-export function typeName(name) {
-  return name.replace(/(?:^|_)([a-z0-9])/gi, (_, c) => c.toUpperCase());
-}
-export function blockUnionName(entryName, fieldKey) {
-  return `${typeName(entryName)}${typeName(fieldKey)}Block`;
-}
-export function blockTypeName(entryName, fieldKey, blockName) {
-  return `${typeName(entryName)}${typeName(fieldKey)}${typeName(blockName)}`;
-}
+import {
+  blockTypeName,
+  blocksFieldTypeName,
+  isPrivateField,
+  isRequiredField,
+  isTranslatableField,
+  typeName
+} from "./index.js";
+export { blockTypeName, blocksFieldTypeName, typeName };
 function scalarFor(field) {
   switch (field.type) {
     case "number":
@@ -58,7 +57,7 @@ function fieldSdl(config, entryName, key, field) {
   if (field.type === "media") return `  ${key}: CmsMedia`;
   if (field.type === "select" && field.multiple) return `  ${key}: [String!]!`;
   if (field.type === "blocks")
-    return `  ${key}: [${blockUnionName(entryName, key)}!]${isRequiredField(field) ? "!" : ""}`;
+    return `  ${key}: [${blocksFieldTypeName(entryName, key)}!]${isRequiredField(field) ? "!" : ""}`;
   return `  ${key}: ${scalarFor(field)}${isRequiredField(field) ? "!" : ""}`;
 }
 function entrySdl(config, name, entry) {
@@ -73,25 +72,44 @@ function entrySdl(config, name, entry) {
 ${lines.join("\n")}
 }`;
 }
+function blockFieldSdl(field) {
+  if (field.type === "media") return { base: "CmsMedia", nonNull: false };
+  return { base: scalarFor(field), nonNull: !!field.required };
+}
+function sharedBlockFieldsSdl(field) {
+  const blocks = Object.values(field.blocks ?? {});
+  const first = blocks[0];
+  if (!first) return [];
+  const lines = [];
+  for (const key of Object.keys(first.fields)) {
+    const rendered = blocks.map((block) => block.fields[key]);
+    if (rendered.some((blockField) => !blockField)) continue;
+    const types = rendered.map((blockField) => blockFieldSdl(blockField));
+    if (types.some((type) => type.base !== types[0].base)) continue;
+    const nonNull = types.every((type) => type.nonNull);
+    lines.push(`  ${key}: ${types[0].base}${nonNull ? "!" : ""}`);
+  }
+  return lines;
+}
 function blocksSdl(name, key, field) {
-  const defs = [];
-  const members = [];
-  for (const [blockName, block] of Object.entries(field.blocks ?? {})) {
-    const gqlType = blockTypeName(name, key, blockName);
-    members.push(gqlType);
+  const blocks = Object.entries(field.blocks ?? {});
+  if (!blocks.length) return [];
+  const interfaceName = blocksFieldTypeName(name, key);
+  const shared = ["  type: String!", ...sharedBlockFieldsSdl(field)];
+  const defs = [`interface ${interfaceName} {
+${shared.join("\n")}
+}`];
+  for (const [blockName, block] of blocks) {
     const lines = ["  type: String!"];
     for (const [blockFieldKey, blockField] of Object.entries(block.fields)) {
-      if (blockField.type === "media") {
-        lines.push(`  ${blockFieldKey}: CmsMedia`);
-        continue;
-      }
-      lines.push(`  ${blockFieldKey}: ${scalarFor(blockField)}${blockField.required ? "!" : ""}`);
+      const type = blockFieldSdl(blockField);
+      lines.push(`  ${blockFieldKey}: ${type.base}${type.nonNull ? "!" : ""}`);
     }
-    defs.push(`type ${gqlType} {
+    const gqlType = blockTypeName(name, key, blockName);
+    defs.push(`type ${gqlType} implements ${interfaceName} {
 ${lines.join("\n")}
 }`);
   }
-  if (members.length) defs.push(`union ${blockUnionName(name, key)} = ${members.join(" | ")}`);
   return defs;
 }
 function filterSdl(name, entry) {
@@ -119,7 +137,8 @@ const COMMON_SDL = [
   "input FloatFilter {\n  eq: Float\n  neq: Float\n  gt: Float\n  gte: Float\n  lt: Float\n  lte: Float\n  in: [Float!]\n  isNull: Boolean\n}",
   "input StringFilter {\n  eq: String\n  neq: String\n  gt: String\n  gte: String\n  lt: String\n  lte: String\n  like: String\n  in: [String!]\n  isNull: Boolean\n}",
   "input BooleanFilter {\n  eq: Boolean\n  neq: Boolean\n  isNull: Boolean\n}",
-  "type CmsMedia {\n  key: String!\n  url: String\n  type: String!\n  alt: String\n  folder: String\n  mime: String\n  size: Int\n  width: Int\n  height: Int\n}"
+  "enum CmsMediaType {\n  image\n  video\n  file\n}",
+  "type CmsMedia {\n  key: String!\n  url: String\n  type: CmsMediaType!\n  alt: String\n  folder: String\n  mime: String\n  size: Int\n  width: Int\n  height: Int\n}"
 ];
 export function renderGraphqlSdl(config) {
   const queryLines = [];

package/dist/runtime/shared/index.d.ts

@@ -98,6 +98,9 @@ export interface CmsEntry {
     table?: CmsTable;
 }
 export type CmsConfig = Record<string, CmsEntry>;
+export declare function typeName(name: string): string;
+export declare function blocksFieldTypeName(entryName: string, fieldKey: string): string;
+export declare function blockTypeName(entryName: string, fieldKey: string, blockName: string): string;
 interface FieldInputBase {
     label: string;
     required?: boolean;

package/dist/runtime/shared/index.js

@@ -184,6 +184,15 @@ export function localizeBlocks(field, value, locale, defaultLocale) {
   if (!Array.isArray(value)) return value;
   return value.map((item) => localizeBlock(field, item, locale, defaultLocale));
 }
+export function typeName(name) {
+  return name.replace(/(?:^|_)([a-z0-9])/gi, (_, c) => c.toUpperCase());
+}
+export function blocksFieldTypeName(entryName, fieldKey) {
+  return `${typeName(entryName)}${typeName(fieldKey)}Block`;
+}
+export function blockTypeName(entryName, fieldKey, blockName) {
+  return `${typeName(entryName)}${typeName(fieldKey)}${typeName(blockName)}`;
+}
 export function defineCmsConfig(config) {
   return config;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xleddyl/nuxt-cms",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Lightweight CMS that ships with your Nuxt app: runs on the Nitro server, content types defined in code, /cms admin panel, GraphQL API, SQLite or Postgres. No external CMS needed!",
   "license": "MIT",
   "author": "Edoardo Alberti (https://github.com/xleddyl)",