@pattern-stack/codegen 0.2.0

package/templates/entity/new/frontend/entity/combined.ejs.t

@@ -0,0 +1,474 @@
+---
+to: "<%= generate.structure === 'monolithic' ? `${locations.frontendGenerated.path}/${generate.fileNaming === 'plural' ? plural : name}.ts` : '' %>"
+skip_if: <%= !frontendEnabled || (generate.structure !== 'monolithic') %>
+force: true
+---
+/**
+ * <%= className %> - Generated Entity Module
+ *
+ * AUTO-GENERATED by entity codegen - do not edit directly.
+ * Source: entities/<%= name %>.yaml
+ *
+ * This file contains everything needed for the <%= className %> entity:
+ * - Types (base + resolved with relations)
+ * - Collection (Electric sync with optimistic mutations)
+ * - Hooks (useMany, useOne with auto-resolved relations)
+ * - Mutations (insert, update, delete)
+ * - Field metadata (for DataGrid, forms, admin)
+ */
+
+<%
+// Type import: depends on typeNaming config
+// 'entity' = source exports OpportunityEntity, 'plain' = source exports Opportunity
+const importedTypeName = generate.typeNaming === 'plain' ? className : className + 'Entity';
+// Collection variable name depends on collectionNaming config
+const collectionVar = generate.collectionNaming === 'plural' ? collectionVarNamePlural : collectionVarName;
+// Hook return key depends on hookReturnStyle config
+const returnKey = generate.hookReturnStyle === 'named' ? pluralCamelName : 'data';
+const returnKeySingular = generate.hookReturnStyle === 'named' ? camelName : 'data';
+-%>
+<% if (generate.mutations && (exposeTrpc || exposeRepository)) { -%>
+import { useState, useCallback } from 'react';
+<% } -%>
+<% if (frontend.sync.columnMapper) { -%>
+import { <%= frontend.sync.columnMapper %> } from '@electric-sql/client';
+<% } -%>
+import { <%= camelName %>Schema, type <%= importedTypeName %> } from '<%= locations.dbEntities.import %><% if (!locations.dbEntities.barrelExport) { %>/<%= name %><% } %>';
+<% if (exposeTrpc) { -%>
+import { trpc } from '<%= locations.trpcClient.import %>';
+<% } -%>
+import { electricCollectionOptions } from '@tanstack/electric-db-collection';
+import { createCollection<% if (generate.hookStyle === 'useLiveQuery') { %>, useLiveQuery, eq<% } %> } from '@tanstack/react-db';
+<% if (generate.fieldMetadata) { -%>
+import type { FieldMeta, FieldType, FieldImportance } from '<%= locations.frontendFieldMetaTypes.import %>/field-meta';
+<% } -%>
+<% if (frontend.auth.function) { -%>
+import { <%= frontend.auth.function %> } from '<%= locations.frontendCollectionsAuth.import %>';
+<% } -%>
+<% if (frontend.sync.apiBaseUrlImport) { -%>
+import { API_BASE_URL } from '<%= frontend.sync.apiBaseUrlImport %>';
+<% } -%>
+<%
+// Collect unique belongs_to targets for imports (FK resolution)
+// Only import if fkResolution is enabled (default: true)
+const importedEntities = new Set();
+if (generate.fkResolution !== false) {
+  existingBelongsTo.forEach((rel) => {
+    if (rel.target !== name) {
+      importedEntities.add(rel.target);
+    }
+  });
+}
+-%>
+<% if (importedEntities.size > 0) { -%>
+
+// Import related collections for FK resolution
+<% importedEntities.forEach((target) => {
+  const targetCamel = target.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+  // Simple pluralization matching prompt.js pluralize function
+  const targetPlural = target.endsWith('y') ? target.slice(0, -1) + 'ies' :
+    (target.endsWith('s') || target.endsWith('x') || target.endsWith('ch') || target.endsWith('sh')) ? target + 'es' : target + 's';
+  const targetFileName = generate.fileNaming === 'plural' ? targetPlural : target;
+  const targetCamelPlural = targetCamel.endsWith('y') ? targetCamel.slice(0, -1) + 'ies' : targetCamel + 's';
+  const targetCollectionVar = generate.collectionNaming === 'plural' ? targetCamelPlural : targetCamel;
+-%>
+import { <%= targetCollectionVar %>Collection } from './<%= targetFileName %>';
+<% }); -%>
+<% importedEntities.forEach((target) => {
+  const targetClass = target.charAt(0).toUpperCase() + target.slice(1).replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+-%>
+import type { <%= generate.typeNaming === 'plain' ? targetClass : targetClass + 'Entity' %> } from '<%= locations.dbEntities.import %><% if (!locations.dbEntities.barrelExport) { %>/<%= target %><% } %>';
+<% }); -%>
+<% } -%>
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Base entity from database */
+<% if (generate.typeNaming === 'plain') { -%>
+export type { <%= className %> };
+<% } else { -%>
+export type <%= className %> = <%= importedTypeName %>;
+<% } -%>
+<% if (existingBelongsTo.length > 0 && generate.fkResolution !== false) { -%>
+
+/** Entity with resolved FK relations (only includes relations with existing targets) */
+export interface <%= className %>Resolved extends <%= className %> {
+<% existingBelongsTo.forEach((rel) => { -%>
+<% // Use local type for self-referential, imported type for others -%>
+<%   const relTypeName = rel.target === name ? className : (generate.typeNaming === 'plain' ? rel.targetClass : rel.targetClass + 'Entity'); -%>
+	<%= rel.name %>?: <%= relTypeName %>;
+<% }); -%>
+}
+<% } else { -%>
+
+/** Entity type (no FK relations to resolve) */
+export type <%= className %>Resolved = <%= className %>;
+<% } -%>
+
+// ============================================================================
+// Collection (Electric sync with optimistic mutations)
+// ============================================================================
+<% if (hasSoftDelete) { -%>
+
+// TODO: Backend Electric shape endpoint should filter soft-deleted records
+// by including WHERE deleted_at IS NULL in the shape configuration.
+// Without this filter, soft-deleted records will reappear after Electric sync.
+<% } -%>
+
+export const <%= collectionVar %> = createCollection(
+	electricCollectionOptions({
+		id: '<%= plural %>',
+		shapeOptions: {
+<% if (frontend.sync.useTableParam) { -%>
+<% if (frontend.sync.wrapInUrlConstructor !== false) { -%>
+			url: new URL(
+				'<%= frontend.sync.shapeUrl %>',
+				typeof window !== 'undefined'
+					? window.location.origin
+					: 'http://localhost:5173',
+			).toString(),
+<% } else { -%>
+			url: '<%= frontend.sync.shapeUrl %>',
+<% } -%>
+			params: {
+				table: '<%= plural %>',
+			},
+<% } else { -%>
+<% if (frontend.sync.wrapInUrlConstructor !== false) { -%>
+			url: new URL(
+				`<%= frontend.sync.shapeUrl %>/<%= plural %>`,
+				typeof window !== 'undefined'
+					? window.location.origin
+					: 'http://localhost:5173',
+			).toString(),
+<% } else { -%>
+			url: `<%= frontend.sync.shapeUrl %>/<%= plural %>`,
+<% } -%>
+<% } -%>
+<% if (frontend.auth.function) { -%>
+			headers: {
+				Authorization: <%= frontend.auth.function %>(),
+			},
+<% } -%>
+			parser: {
+<% Object.entries(frontend.parsers).forEach(([type, fn]) => { -%>
+				<%- type %>: <%- fn %>,
+<% }); -%>
+			},
+<% if (frontend.sync.columnMapper) { -%>
+<% if (frontend.sync.columnMapperNeedsCall !== false) { -%>
+			columnMapper: <%= frontend.sync.columnMapper %>(),
+<% } else { -%>
+			columnMapper: <%= frontend.sync.columnMapper %>,
+<% } -%>
+<% } -%>
+		},
+		schema: <%= camelName %>Schema,
+		getKey: (item) => item.id,
+<% if (generate.mutations && (exposeTrpc || exposeRepository)) { -%>
+<% if (exposeTrpc) { -%>
+		onInsert: async ({ transaction }) => {
+			const { modified } = transaction.mutations[0];
+			const result = await trpc.<%= plural %>.create.mutate(modified);
+			return { txid: result.txid };
+		},
+		onUpdate: async ({ transaction }) => {
+			const { modified } = transaction.mutations[0];
+			const result = await trpc.<%= plural %>.update.mutate({ id: modified.id, data: modified });
+			return { txid: result.txid };
+		},
+		onDelete: async ({ transaction }) => {
+			const { original } = transaction.mutations[0];
+			const result = await trpc.<%= plural %>.delete.mutate({ id: original.id });
+			return { txid: result.txid };
+		},
+<% } -%>
+<% } -%>
+	}),
+);
+
+// ============================================================================
+// Resolution (FK lookup - internal use)
+// ============================================================================
+<% if (existingBelongsTo.length > 0 && generate.fkResolution !== false) { -%>
+
+function resolveRelations(entity: <%= className %>): <%= className %>Resolved {
+	return {
+		...entity,
+<% existingBelongsTo.forEach((rel) => {
+  const targetCamel = rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+  const targetCamelPlural = targetCamel.endsWith('y') ? targetCamel.slice(0, -1) + 'ies' : targetCamel + 's';
+  const targetCollectionVar = generate.collectionNaming === 'plural' ? targetCamelPlural : targetCamel;
+-%>
+		<%= rel.name %>: entity.<%= rel.foreignKeyCamel %>
+			? <%= targetCollectionVar %>Collection.state.get(entity.<%= rel.foreignKeyCamel %>)
+			: undefined,
+<% }); -%>
+	};
+}
+<% } else { -%>
+
+function resolveRelations(entity: <%= className %>): <%= className %>Resolved {
+	return entity;
+}
+<% } -%>
+
+// ============================================================================
+// Hooks (React hooks returning resolved entities)
+// ============================================================================
+<% if (generate.hookStyle === 'useLiveQuery') { -%>
+
+/** Get all <%= plural %> with relations resolved */
+export function use<%= classNamePlural %>() {
+	const result = useLiveQuery((q) => q.from({ <%= collectionVar %> }), []);
+	return {
+		<%= returnKey %>: result.data?.map(resolveRelations) ?? [],
+		isLoading: result.isLoading,
+	};
+}
+
+/** Get single <%= camelName %> by ID with relations resolved */
+export function use<%= className %>(id: string | undefined) {
+	const result = useLiveQuery(
+		(q) => {
+			if (!id) return undefined;
+			return q
+				.from({ <%= collectionVar %> })
+				.where(({ <%= collectionVar %> }) => eq(<%= collectionVar %>.id, id));
+		},
+		[id],
+	);
+	const entity = result.data?.[0];
+	return {
+		<%= returnKeySingular %>: entity ? resolveRelations(entity) : undefined,
+		isLoading: result.isLoading,
+	};
+}
+<% } else { -%>
+
+/** Get all <%= plural %> with relations resolved */
+export function use<%= classNamePlural %>(): <%= className %>Resolved[] {
+	const raw = <%= collectionVar %>.useMany();
+	return raw.map(resolveRelations);
+}
+
+/** Get single <%= camelName %> by ID with relations resolved */
+export function use<%= className %>(id: string | undefined): <%= className %>Resolved | undefined {
+	const raw = <%= collectionVar %>.useOne(id);
+	return raw ? resolveRelations(raw) : undefined;
+}
+<% } -%>
+
+<% if (generate.mutations && (exposeTrpc || exposeRepository)) { -%>
+// ============================================================================
+// Mutations (Optimistic updates)
+// ============================================================================
+
+export function insert<%= className %>(data: Omit<<%= className %>, 'id'<% if (hasTimestamps) { %> | 'createdAt' | 'updatedAt'<% } %>>) {
+	return <%= collectionVar %>.insert({
+		id: crypto.randomUUID(),
+<% if (hasTimestamps) { -%>
+		createdAt: new Date(),
+		updatedAt: new Date(),
+<% } -%>
+		...data,
+	} as <%= className %>);
+}
+
+export function update<%= className %>(id: string, fn: (draft: <%= className %>) => void) {
+	return <%= collectionVar %>.update(id, fn);
+}
+
+export function delete<%= className %>(id: string) {
+	return <%= collectionVar %>.delete(id);
+}
+
+// ============================================================================
+// Mutation Hooks (Error tracking wrappers)
+// ============================================================================
+
+type MutationHookResult<TFn extends (...args: any[]) => any> = {
+	mutate: TFn;
+	error: Error | null;
+	clearError: () => void;
+};
+
+export function useCreate<%= className %>(): MutationHookResult<typeof insert<%= className %>> {
+	const [error, setError] = useState<Error | null>(null);
+
+	const mutate = useCallback<typeof insert<%= className %>>((data) => {
+		try {
+			insert<%= className %>(data);
+			setError(null);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			setError(error);
+			throw error;
+		}
+	}, []);
+
+	const clearError = useCallback(() => setError(null), []);
+	return { mutate, error, clearError };
+}
+
+export function useUpdate<%= className %>(): MutationHookResult<typeof update<%= className %>> {
+	const [error, setError] = useState<Error | null>(null);
+
+	const mutate = useCallback<typeof update<%= className %>>((id, fn) => {
+		try {
+			update<%= className %>(id, fn);
+			setError(null);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			setError(error);
+			throw error;
+		}
+	}, []);
+
+	const clearError = useCallback(() => setError(null), []);
+	return { mutate, error, clearError };
+}
+
+export function useDelete<%= className %>(): MutationHookResult<typeof delete<%= className %>> {
+	const [error, setError] = useState<Error | null>(null);
+
+	const mutate = useCallback<typeof delete<%= className %>>((id) => {
+		try {
+			delete<%= className %>(id);
+			setError(null);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			setError(error);
+			throw error;
+		}
+	}, []);
+
+	const clearError = useCallback(() => setError(null), []);
+	return { mutate, error, clearError };
+}
+<% } -%>
+<% if (generate.fieldMetadata) { -%>
+
+// ============================================================================
+// Field Metadata (for DataGrid, forms, admin)
+// ============================================================================
+
+export const <%= camelName %>Fields: Record<string, FieldMeta<<%= className %>Resolved>> = {
+<% fields.forEach((field) => { -%>
+<% // Skip entity ref internal fields from metadata display
+if (field.isEntityRefType || field.isEntityRefId) return;
+-%>
+	<%= field.camelName %>: {
+		field: '<%= field.camelName %>',
+		label: '<%= field.ui_label %>',
+		type: '<%= field.ui_type %>' as FieldType,
+		importance: '<%= field.ui_importance %>' as FieldImportance,
+<% if (field.ui_sortable) { -%>
+		sortable: true,
+<% } -%>
+<% if (field.ui_filterable) { -%>
+		filterable: true,
+<% } -%>
+<% if (field.ui_format) { -%>
+		format: <%- JSON.stringify(field.ui_format) %>,
+<% } -%>
+<% if (field.hasChoices) { -%>
+		choices: <%- JSON.stringify(field.choices) %>,
+<% } -%>
+<% if (field.foreignKey) { -%>
+		reference: '<%= field.foreignKey.split('.')[0] %>',
+<% } -%>
+	},
+<% }); -%>
+<% // Add resolved relation fields to metadata
+belongsToRelations.forEach((rel) => { -%>
+	<%= rel.name %>: {
+		field: '<%= rel.name %>',
+		label: '<%= rel.targetClass.replace(/([A-Z])/g, ' $1').trim() %>',
+		type: 'entity' as FieldType,
+		importance: 'secondary' as FieldImportance,
+		reference: '<%= rel.targetPlural %>',
+	},
+<% }); -%>
+<% if (hasTimestamps) { -%>
+	createdAt: {
+		field: 'createdAt',
+		label: 'Created',
+		type: 'datetime' as FieldType,
+		importance: 'tertiary' as FieldImportance,
+		format: { dateFormat: 'relative' },
+	},
+	updatedAt: {
+		field: 'updatedAt',
+		label: 'Updated',
+		type: 'datetime' as FieldType,
+		importance: 'tertiary' as FieldImportance,
+		format: { dateFormat: 'relative' },
+	},
+<% } -%>
+};
+
+export const <%= camelName %>Metadata = {
+	name: '<%= name %>',
+	plural: '<%= plural %>',
+	displayName: '<%= className.replace(/([A-Z])/g, ' $1').trim() %>',
+	displayNamePlural: '<%= classNamePlural.replace(/([A-Z])/g, ' $1').trim() %>',
+
+	fields: <%= camelName %>Fields,
+
+	// Display configuration
+	primaryFields: [
+<% fields.filter(f => f.ui_importance === 'primary').forEach(f => { -%>
+		'<%= f.camelName %>',
+<% }); -%>
+	],
+	searchFields: [
+<% fields.filter(f => f.ui_filterable).forEach(f => { -%>
+		'<%= f.camelName %>',
+<% }); -%>
+	],
+	defaultSort: { field: '<% if (hasTimestamps) { %>createdAt<% } else { %>id<% } %>', direction: 'desc' as const },
+
+	// Capabilities
+	capabilities: {
+		create: <%= exposeRepository || exposeTrpc %>,
+		update: <%= exposeRepository || exposeTrpc %>,
+		delete: <%= exposeRepository || exposeTrpc %>,
+		list: true,
+		get: true,
+	},
+} as const;
+<% } -%>
+
+// ============================================================================
+// Export bundle for registry
+// ============================================================================
+
+export const <%= camelName %> = {
+	// Collection
+	collection: <%= collectionVar %>,
+
+	// Hooks
+	useMany: use<%= classNamePlural %>,
+	useOne: use<%= className %>,
+<% if (generate.mutations && (exposeTrpc || exposeRepository)) { -%>
+
+	// Mutations
+	insert: insert<%= className %>,
+	update: update<%= className %>,
+	delete: delete<%= className %>,
+
+	// Mutation Hooks
+	useCreate: useCreate<%= className %>,
+	useUpdate: useUpdate<%= className %>,
+	useDelete: useDelete<%= className %>,
+<% } -%>
+<% if (generate.fieldMetadata) { -%>
+
+	// Metadata
+	fields: <%= camelName %>Fields,
+	metadata: <%= camelName %>Metadata,
+<% } -%>
+} as const;

package/templates/entity/new/frontend/entity/fields.ejs.t

@@ -0,0 +1,104 @@
+---
+to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.path}/${name}/fields.ts` : generate.structure === 'concern-first' ? `${locations.frontendGenerated.path}/fields/${name}.ts` : '' %>"
+skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic' || !generate.fieldMetadata) %>
+force: true
+---
+/**
+ * <%= className %> Field Metadata
+ * Generated by entity codegen - do not edit directly
+ *
+ * Field definitions for DataGrid, forms, and admin interfaces
+ */
+
+import type { FieldMeta, FieldType, FieldImportance } from '<%= locations.frontendFieldMetaTypes.import %>/field-meta';
+<% if (generate.structure === 'entity-first') { -%>
+import type { <%= className %>Resolved } from './types';
+<% } else if (generate.structure === 'concern-first') { -%>
+import type { <%= className %>Resolved } from '../types/<%= name %>';
+<% } -%>
+
+export const <%= camelName %>Fields: Record<string, FieldMeta<<%= className %>Resolved>> = {
+<% fields.forEach((field) => { -%>
+<% // Skip entity ref internal fields from metadata display
+if (field.isEntityRefType || field.isEntityRefId) return;
+-%>
+	<%= field.camelName %>: {
+		field: '<%= field.camelName %>',
+		label: '<%= field.ui_label %>',
+		type: '<%= field.ui_type %>' as FieldType,
+		importance: '<%= field.ui_importance %>' as FieldImportance,
+<% if (field.ui_sortable) { -%>
+		sortable: true,
+<% } -%>
+<% if (field.ui_filterable) { -%>
+		filterable: true,
+<% } -%>
+<% if (field.ui_format) { -%>
+		format: <%- JSON.stringify(field.ui_format) %>,
+<% } -%>
+<% if (field.hasChoices) { -%>
+		choices: <%- JSON.stringify(field.choices) %>,
+<% } -%>
+<% if (field.foreignKey) { -%>
+		reference: '<%= field.foreignKey.split('.')[0] %>',
+<% } -%>
+	},
+<% }); -%>
+<% // Add resolved relation fields to metadata
+belongsToRelations.forEach((rel) => { -%>
+	<%= rel.name %>: {
+		field: '<%= rel.name %>',
+		label: '<%= rel.targetClass.replace(/([A-Z])/g, ' $1').trim() %>',
+		type: 'entity' as FieldType,
+		importance: 'secondary' as FieldImportance,
+		reference: '<%= rel.targetPlural %>',
+	},
+<% }); -%>
+<% if (hasTimestamps) { -%>
+	createdAt: {
+		field: 'createdAt',
+		label: 'Created',
+		type: 'datetime' as FieldType,
+		importance: 'tertiary' as FieldImportance,
+		format: { dateFormat: 'relative' },
+	},
+	updatedAt: {
+		field: 'updatedAt',
+		label: 'Updated',
+		type: 'datetime' as FieldType,
+		importance: 'tertiary' as FieldImportance,
+		format: { dateFormat: 'relative' },
+	},
+<% } -%>
+};
+
+export const <%= camelName %>Metadata = {
+	name: '<%= name %>',
+	plural: '<%= plural %>',
+	displayName: '<%= className.replace(/([A-Z])/g, ' $1').trim() %>',
+	displayNamePlural: '<%= classNamePlural.replace(/([A-Z])/g, ' $1').trim() %>',
+
+	fields: <%= camelName %>Fields,
+
+	// Display configuration
+	primaryFields: [
+<% fields.filter(f => f.ui_importance === 'primary').forEach(f => { -%>
+		'<%= f.camelName %>',
+<% }); -%>
+	],
+	searchFields: [
+<% fields.filter(f => f.ui_filterable).forEach(f => { -%>
+		'<%= f.camelName %>',
+<% }); -%>
+	],
+	defaultSort: { field: '<% if (hasTimestamps) { %>createdAt<% } else { %>id<% } %>', direction: 'desc' as const },
+
+	// Capabilities
+	capabilities: {
+		create: <%= exposeRepository || exposeTrpc %>,
+		update: <%= exposeRepository || exposeTrpc %>,
+		delete: <%= exposeRepository || exposeTrpc %>,
+		list: true,
+		get: true,
+	},
+} as const;

package/templates/entity/new/frontend/entity/hooks.ejs.t

@@ -0,0 +1,73 @@
+---
+to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.path}/${generate.fileNaming === 'plural' ? plural : name}/hooks.ts` : generate.structure === 'concern-first' ? `${locations.frontendGenerated.path}/hooks/${generate.fileNaming === 'plural' ? plural : name}.ts` : '' %>"
+skip_if: <%= !frontendEnabled || (generate.structure === 'monolithic') %>
+force: true
+---
+/**
+ * <%= className %> Hooks
+ * Generated by entity codegen - do not edit directly
+ *
+ * React hooks returning resolved entities with relations
+ */
+
+<%
+// Collection variable name depends on collectionNaming config
+const collectionVar = generate.collectionNaming === 'plural' ? collectionVarNamePlural : collectionVarName;
+// File name for imports depends on fileNaming config
+const fileName = generate.fileNaming === 'plural' ? plural : name;
+// Hook return key depends on hookReturnStyle config
+const returnKey = generate.hookReturnStyle === 'named' ? pluralCamelName : 'data';
+const returnKeySingular = generate.hookReturnStyle === 'named' ? camelName : 'data';
+-%>
+<% if (generate.hookStyle === 'useLiveQuery') { -%>
+import { useLiveQuery, eq } from '@tanstack/react-db';
+<% } -%>
+<% if (generate.structure === 'entity-first') { -%>
+import { <%= collectionVar %>, resolveRelations } from './collection';
+import type { <%= className %>Resolved } from './types';
+<% } else if (generate.structure === 'concern-first') { -%>
+import { <%= collectionVar %>, resolveRelations } from '../collections/<%= fileName %>';
+import type { <%= className %>Resolved } from '../types/<%= fileName %>';
+<% } -%>
+<% if (generate.hookStyle === 'useLiveQuery') { -%>
+
+/** Get all <%= plural %> with relations resolved */
+export function use<%= classNamePlural %>() {
+	const result = useLiveQuery((q) => q.from({ <%= collectionVar %> }), []);
+	return {
+		<%= returnKey %>: result.data?.map(resolveRelations) ?? [],
+		isLoading: result.isLoading,
+	};
+}
+
+/** Get single <%= camelName %> by ID with relations resolved */
+export function use<%= className %>(id: string | undefined) {
+	const result = useLiveQuery(
+		(q) => {
+			if (!id) return undefined;
+			return q
+				.from({ <%= collectionVar %> })
+				.where(({ <%= collectionVar %> }) => eq(<%= collectionVar %>.id, id));
+		},
+		[id],
+	);
+	const entity = result.data?.[0];
+	return {
+		<%= returnKeySingular %>: entity ? resolveRelations(entity) : undefined,
+		isLoading: result.isLoading,
+	};
+}
+<% } else { -%>
+
+/** Get all <%= plural %> with relations resolved */
+export function use<%= classNamePlural %>(): <%= className %>Resolved[] {
+	const raw = <%= collectionVar %>.useMany();
+	return raw.map(resolveRelations);
+}
+
+/** Get single <%= camelName %> by ID with relations resolved */
+export function use<%= className %>(id: string | undefined): <%= className %>Resolved | undefined {
+	const raw = <%= collectionVar %>.useOne(id);
+	return raw ? resolveRelations(raw) : undefined;
+}
+<% } -%>

package/templates/entity/new/frontend/entity/index.ejs.t

@@ -0,0 +1,21 @@
+---
+to: "<%= generate.structure === 'entity-first' ? `${locations.frontendGenerated.path}/${name}/index.ts` : '' %>"
+skip_if: <%= !frontendEnabled || (generate.structure !== 'entity-first') %>
+force: true
+---
+/**
+ * <%= className %> - Entity Module
+ * Generated by entity codegen - do not edit directly
+ *
+ * Barrel export for all <%= className %> components
+ */
+
+export * from './types';
+export * from './collection';
+export * from './hooks';
+<% if (generate.mutations && (exposeTrpc || exposeRepository)) { %>
+export * from './mutations';
+<% } %>
+<% if (generate.fieldMetadata) { %>
+export * from './fields';
+<% } %>