@frigear-nu/module-kit 0.0.3 → 0.0.4

package/README.md

@@ -7,51 +7,166 @@ A simple nuxt module to simplify development of other nuxt modules within frigea
 - Be a shared module kit for building nuxt modules within frigear – as generic as possible within the frigear requirements
 - E.g building a 'user' or 'blog' or 'post' module for frigear-nu
 
-## Extending a database table
+## Utils & composables
 
-Modules can register a table schema using `extendDatabaseTable` from `@frigear-nu/module-kit/utils`:
+All of the helpers below are exported from `@frigear-nu/module-kit/utils`.
+
+### Module helpers
+
+#### `registerModule`
+
+Registers a module name against `nuxt.options.moduleKit._modules`, de-duplicating entries. Useful during a module's
+`setup()` to keep track of which Frigear modules are active in the current Nuxt app:
 
 ```ts
-extendDatabaseTable(nuxt, {
+import { registerModule } from '@frigear-nu/module-kit/utils'
+
+registerModule('@frigear-nu/users', nuxt)
+```
+
+#### `defineModulePage`
+
+Tags a `NuxtPage` with the owning module's name in `page.meta.moduleName`, so pages registered by a module can be
+identified later (e.g. for navigation or permission checks):
+
+```ts
+import { defineModulePage } from '@frigear-nu/module-kit/utils'
+
+extendPages((pages) => {
+  pages.push(defineModulePage('@frigear-nu/users', {
+    name: 'users-profile',
+    path: '/users/profile',
+    file: resolver.resolve('./runtime/pages/profile.vue'),
+  }))
+})
+```
+
+### URL helpers
+
+#### `moduleUrl` and `moduleApiUrl`
+
+Build consistent, kebab-cased URLs for a module's pages and API routes. If `path` starts with `/` it is treated as
+absolute and the module name is not prefixed:
+
+```ts
+import { moduleUrl, moduleApiUrl } from '@frigear-nu/module-kit/utils'
+
+moduleUrl('OAuthServer') // => '/o-auth-server'
+moduleUrl('OAuthServer', 'login') // => '/o-auth-server/login'
+moduleApiUrl('OAuthServer', 'token') // => '/api/o-auth-server/token'
+```
+
+### Database schema helpers
+
+These helpers let one module own a Drizzle table while letting other modules (and host applications) extend it with
+additional columns, without the owning module needing to know about them.
+
+#### `registerDatabaseTable`
+
+Modules register a table schema using `registerDatabaseTable`. The simplest usage needs no wrapper at all — `schema`
+can be a *regular* drizzle file:
+
+```ts
+// runtime/db/schema.sqlite.ts
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+
+export const users = sqliteTable('users', {
+  id: integer().primaryKey({ autoIncrement: true }),
+  email: text().notNull().unique(),
+})
+```
+
+```ts
+import { registerDatabaseTable } from '@frigear-nu/module-kit/utils'
+
+registerDatabaseTable(nuxt, {
   name: 'users',
-  factory: 'defineUsersTable',
   resolver: createResolver(import.meta.url),
   schema: dialect => `./runtime/db/schema.${dialect}`,
-  override: options.settings?.schemas?.users,
+})
+```
+
+#### `extendDatabaseTable`
+
+Other modules can register column files during setup. These can be regular files too — either a full table
+definition or a plain columns object, both without any helper wrapper:
+
+```ts
+import { extendDatabaseTable } from '@frigear-nu/module-kit/utils'
+
+extendDatabaseTable(nuxt, {
+  name: 'users',
+  resolver: createResolver(import.meta.url),
+  file: dialect => `./runtime/db/extra.${dialect}`,
 })
 ```
 
 ```ts
-import { ColumnBuilderBase } from "drizzle-orm";
+// runtime/db/extra.sqlite.ts
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core'
 
-const defineUsersTable = (extras: Record<string, ColumnBuilderBase>) => {
-  return sqliteTable('users', {
+export const users = sqliteTable('users', {
+  locale: text().default('da'),
+})
+```
+
+Module-kit parses each file's exported table (or plain object) matching `name`, and merges their columns directly —
+later registrations override columns from earlier ones with the same key — before generating a single `sqliteTable(...)`
+call with the merged columns and deduplicated imports. The base `schema` file must export a genuine table call (e.g.
+`sqliteTable('users', { ... })`) matching `name`, since it determines which factory (`sqliteTable`/`pgTable`/etc.) and
+SQL table name to use for the merged result.
+
+#### Using a `factory`
+
+Pass `factory` to `registerDatabaseTable` when you need shared defaults (e.g. timestamps) applied consistently across
+dialects. Wrap the factory with `defineExtendableTable` so it receives a single `{ name, columns }` object instead of
+a plain columns object — passing `name` through means the table's name only has to be maintained in one place, the
+`registerDatabaseTable` call, instead of being duplicated as a string literal inside the factory itself. The factory
+must spread `columns` *last*, after its own fields (including timestamps), so extended columns always end up last in
+the generated migration:
+
+```ts
+import type { ColumnBuilderBase } from 'drizzle-orm'
+import { defineExtendableTable } from '@frigear-nu/module-kit/utils'
+
+const defineUsersTable = defineExtendableTable(({ name, columns }: { name: string, columns: Record<string, ColumnBuilderBase> }) => {
+  return sqliteTable(name, {
     id: serial('id').primaryKey(),
     email: text('email').notNull().unique(),
     password: text('password').notNull(),
     createdAt: timestamp('created_at').defaultNow().notNull(),
     updatedAt: timestamp('updated_at').defaultNow().notNull(),
-    ...extras || {},
+    ...columns,
   })
-}
+})
 ```
 
-
-The schema file exports the named factory, which accepts an object of additional columns and returns a table. The factory must spread the received `extra` columns *last* in the object passed to the table builder (after every one of its own fields, including timestamps), so extended columns always end up last in the generated migration, matching the order they were registered in. Other modules can register column files during setup:
-
 ```ts
-registerDatabaseTableExtension(nuxt, {
+registerDatabaseTable(nuxt, {
   name: 'users',
+  factory: 'defineUsersTable',
   resolver: createResolver(import.meta.url),
-  file: dialect => `./runtime/db/extra.${dialect}`,
+  schema: dialect => `./runtime/db/schema.${dialect}`,
+  override: options.settings?.schemas?.users,
 })
 ```
 
-Each extension file exports column objects named for their tables. For example, a Nuxt layer can extend several tables in `server/db/extend.sqlite.ts`:
+#### `defineTableColumns`
+
+A typed identity helper for defining a table's extension columns. Each extension file exports column objects named
+for their tables. For example, a Nuxt layer can extend several tables in `server/db/extend.sqlite.ts`:
 
 ```ts
-export const users = defineExtendedColumns({ locale: text().default('da') })
-export const posts = defineExtendedColumns({ summary: text() })
+import { defineTableColumns } from '@frigear-nu/module-kit/utils'
+
+export const users = defineTableColumns({ locale: text().default('da') })
+export const posts = defineTableColumns({ summary: text() })
 ```
 
-Only the export matching the table being built is used. Existing registered files are merged in registration order (later fields replace earlier fields); missing files for a dialect are skipped. Registered files with legacy default exports still work. Nuxt layer files are merged next, from base layers toward the host application. Older `server/db/<name>.extend.<dialect>` files with default exports are also loaded before each layer's shared file, so a shared export can override them. Pass `extensionFile: dialect => 'path/to/columns.' + dialect + '.ts'` to change the per-layer file location. If `override` is a path instead of `'default'`, the host schema replaces the generated table entirely; the path is resolved from the application's root directory.
+Only the export matching the table being built is used. Existing registered files are merged in registration order
+(later fields replace earlier fields); missing files for a dialect are skipped. Registered files with legacy default
+exports still work. Nuxt layer files are merged next, from base layers toward the host application. Older
+`server/db/<name>.extend.<dialect>` files with default exports are also loaded before each layer's shared file, so a
+shared export can override them. Pass `extensionFile: dialect => 'path/to/columns.' + dialect + '.ts'` to change the
+per-layer file location. If `override` is a path instead of `'default'`, the host schema replaces the generated table
+entirely; the path is resolved from the application's root directory.

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.0.0"
   },
-  "version": "0.0.3",
+  "version": "0.0.4",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/utils/regular-table.d.ts

@@ -0,0 +1,23 @@
+export type ParsedTableExport = {
+    /** The callee + sql table name, present only when the export is a table factory call, e.g. `sqliteTable('users', {...})`. */
+    tableCall?: {
+        callee: string;
+        tableName: string;
+    };
+    /** Column (or spread) entries keyed by property name, in source order. Values are the raw `key: value` source text. */
+    properties: Map<string, string>;
+    /** Named imports collected from the file, keyed by module specifier. */
+    imports: Map<string, Set<string>>;
+};
+/**
+ * Parses a "regular" drizzle schema file - i.e. a file that exports a table (or a plain columns object) without
+ * requiring any `defineExtendableTable`/`defineTableColumns` wrapper - and extracts the column properties and
+ * imports belonging to the export matching `exportName`. Supports:
+ *
+ * - `export const users = sqliteTable('users', { ... })` (or `pgTable`/`mysqlTable`, any 2+ arg factory call)
+ * - `export const users = { ... }` (a plain columns object)
+ * - `export const users = defineTableColumns({ ... })` (a single-argument wrapper call)
+ * - `export default { ... }` / `export default sqliteTable(...)` / `export default defineTableColumns({ ... })`
+ *   when `exportName` is `'default'`
+ */
+export declare const parseRegularTableExport: (filePath: string, exportName: string) => ParsedTableExport | undefined;

package/dist/runtime/utils/regular-table.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+export const parseRegularTableExport = (filePath, exportName) => {
+  const text = readFileSync(filePath, "utf8");
+  const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const imports = /* @__PURE__ */ new Map();
+  for (const statement of source.statements) {
+    if (ts.isImportDeclaration(statement) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && ts.isStringLiteralLike(statement.moduleSpecifier)) {
+      const specifiers = imports.get(statement.moduleSpecifier.text) ?? /* @__PURE__ */ new Set();
+      for (const element of statement.importClause.namedBindings.elements) specifiers.add(element.getText());
+      imports.set(statement.moduleSpecifier.text, specifiers);
+    }
+  }
+  const toResult = (initializer) => {
+    let objectLiteral;
+    let tableCall;
+    if (ts.isCallExpression(initializer)) {
+      const args = initializer.arguments;
+      if (args.length >= 2 && ts.isStringLiteralLike(args[0]) && ts.isObjectLiteralExpression(args[1])) {
+        tableCall = { callee: initializer.expression.getText(), tableName: args[0].text };
+        objectLiteral = args[1];
+      } else if (args.length === 1 && ts.isObjectLiteralExpression(args[0])) {
+        objectLiteral = args[0];
+      }
+    } else if (ts.isObjectLiteralExpression(initializer)) {
+      objectLiteral = initializer;
+    }
+    if (!objectLiteral) return void 0;
+    const properties = /* @__PURE__ */ new Map();
+    for (const property of objectLiteral.properties) {
+      if (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) {
+        properties.set(property.name.getText(), property.getText());
+      } else if (ts.isSpreadAssignment(property)) {
+        properties.set(`__spread_${properties.size}`, property.getText());
+      }
+    }
+    return { tableCall, properties, imports };
+  };
+  for (const statement of source.statements) {
+    if (ts.isVariableStatement(statement) && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && declaration.name.text === exportName && declaration.initializer) {
+          const result = toResult(declaration.initializer);
+          if (result) return result;
+        }
+      }
+    } else if (exportName === "default" && ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      const result = toResult(statement.expression);
+      if (result) return result;
+    }
+  }
+  return void 0;
+};

package/dist/runtime/utils/server.d.ts

@@ -16,11 +16,40 @@ declare module '@nuxt/schema' {
         'module-kit:db:table:extend': TableExtenderFn;
     }
 }
-export declare const defineExtendedColumns: <T extends Record<string, ColumnBuilderBase>>(columns: T) => T;
-export declare const extendDatabaseSchema: (nuxt: Nuxt, extender: DbExtenderFn) => Promise<() => void>;
+/**
+ * A typed identity helper for defining a table's extension columns. It exists purely for type
+ * inference/clarity when authoring `server/db/extend.<dialect>.ts` files — it returns the columns
+ * object unchanged.
+ */
+export declare const defineTableColumns: <T extends Record<string, ColumnBuilderBase>>(columns: T) => T;
+type TableDefinerProps = {
+    name: string;
+    columns: Record<string, ColumnBuilderBase>;
+};
+type TableDefinerFn<T> = (props: TableDefinerProps) => T;
+/**
+ * Wraps a Drizzle table factory so it receives `{ name, columns }`, letting the factory pass
+ * `name` straight through to e.g. `sqliteTable(name, columns)` instead of hard-coding it, so the
+ * table name only has to be maintained once, in the `registerDatabaseTable` call.
+ */
+export declare const defineExtendableTable: <T>(table: TableDefinerFn<T>) => (props: TableDefinerProps) => T;
+/**
+ * Lower-level primitive behind `registerDatabaseTable`. Registers a callback on the
+ * `hub:db:schema:extend` hook, which receives the current `dialect` and the `paths` array of
+ * schema files to include in the generated database schema. Most modules should use
+ * `registerDatabaseTable` instead, unless they need full control over how their schema file is
+ * built.
+ */
+export declare const onDatabaseSchemaExtend: (nuxt: Nuxt, extender: DbExtenderFn) => Promise<() => void>;
 type DatabaseTableOptions = {
     name: string;
-    factory: string;
+    /**
+     * The exported factory function name to call with merged extension columns (e.g. `defineUsersTable`), as produced
+     * by `defineExtendableTable`. When omitted, `schema` (and every registered/layer extension file) is treated as a
+     * "regular" drizzle file - e.g. `export const users = sqliteTable('users', { ... })` - and its columns are merged
+     * directly, without requiring any helper wrapper.
+     */
+    factory?: string;
     resolver: ReturnType<typeof createResolver>;
     schema: (dialect: string) => string;
     override?: string;
@@ -31,6 +60,17 @@ type TableExtensionOptions = {
     resolver: ReturnType<typeof createResolver>;
     file: (dialect: string) => string;
 };
-export declare const registerDatabaseTableExtension: (nuxt: Nuxt, options: TableExtensionOptions) => void;
-export declare const extendDatabaseTable: (nuxt: Nuxt, options: DatabaseTableOptions) => Promise<() => void>;
+/**
+ * Registers a column file to be merged into a named table whenever its schema is generated (see
+ * `registerDatabaseTable`). Fires the `module-kit:db:table:extend` hook internally, which
+ * `registerDatabaseTable` listens to.
+ */
+export declare const extendDatabaseTable: (nuxt: Nuxt, options: TableExtensionOptions) => void;
+/**
+ * The table-owning module registers its schema with `registerDatabaseTable`. It generates the
+ * table by importing the named `factory` from `schema`, merging in any columns registered
+ * through `extendDatabaseTable` and any Nuxt-layer extension files, then calling the factory with
+ * `{ name, columns }`.
+ */
+export declare const registerDatabaseTable: (nuxt: Nuxt, options: DatabaseTableOptions) => Promise<() => void>;
 export {};

package/dist/runtime/utils/server.js

@@ -1,12 +1,18 @@
 import { addTemplate, createResolver } from "@nuxt/kit";
 import { existsSync } from "node:fs";
-export const defineExtendedColumns = (columns) => {
+import { parseRegularTableExport } from "./regular-table.js";
+export const defineTableColumns = (columns) => {
   return columns;
 };
-export const extendDatabaseSchema = async (nuxt, extender) => {
+export const defineExtendableTable = (table) => {
+  return (props) => {
+    return table(props);
+  };
+};
+export const onDatabaseSchemaExtend = async (nuxt, extender) => {
   return nuxt.hook("hub:db:schema:extend", extender);
 };
-export const registerDatabaseTableExtension = (nuxt, options) => {
+export const extendDatabaseTable = (nuxt, options) => {
   nuxt.hook("module-kit:db:table:extend", async ({ name, dialect, paths }) => {
     if (name === options.name) {
       const file = await options.resolver.resolvePath(options.file(dialect));
@@ -14,9 +20,9 @@ export const registerDatabaseTableExtension = (nuxt, options) => {
     }
   });
 };
-export const extendDatabaseTable = (nuxt, options) => {
+export const registerDatabaseTable = (nuxt, options) => {
   const { name, factory, resolver, schema, override, extensionFile } = options;
-  return extendDatabaseSchema(nuxt, async ({ dialect, paths }) => {
+  return onDatabaseSchemaExtend(nuxt, async ({ dialect, paths }) => {
     if (override && override !== "default") {
       paths.push(await resolver.resolvePath(override, { cwd: nuxt.options.rootDir }));
       return;
@@ -34,15 +40,55 @@ export const extendDatabaseTable = (nuxt, options) => {
       }
       if (existsSync(extensionPath)) extensions.push({ file: extensionPath, legacy: false });
     }
+    if (!factory) {
+      const schemaPath = await resolver.resolvePath(schema(dialect));
+      const template2 = buildRegularTableTemplate({ name, dialect, schemaPath, extensionFiles: extensions.map(({ file }) => file) });
+      paths.push(template2.dst);
+      return;
+    }
     const template = addTemplate({
       filename: `${name}/schema.${dialect}.ts`,
       write: true,
       getContents: () => `
 import { ${factory} } from ${JSON.stringify(resolver.resolve(schema(dialect)))}
 ${extensions.map(({ file }, index) => `import * as extra${index} from ${JSON.stringify(file)}`).join("\n")}
-export const ${name} = ${factory}({ ${extensions.map(({ legacy }, index) => legacy ? `...(extra${index}[${JSON.stringify(name)} as keyof typeof extra${index}] ?? Object.entries(extra${index}).find(([key]) => key === 'default')?.[1] ?? {})` : `...(extra${index}[${JSON.stringify(name)} as keyof typeof extra${index}] ?? {})`).join(", ")} })
+export const ${name} = ${factory}({ name: ${JSON.stringify(name)}, columns: { ${extensions.map(({ legacy }, index) => legacy ? `...(extra${index}[${JSON.stringify(name)} as keyof typeof extra${index}] ?? Object.entries(extra${index}).find(([key]) => key === 'default')?.[1] ?? {})` : `...(extra${index}[${JSON.stringify(name)} as keyof typeof extra${index}] ?? {})`).join(", ")} } })
 `
     });
     paths.push(template.dst);
   });
 };
+const buildRegularTableTemplate = (options) => {
+  const { name, dialect, schemaPath, extensionFiles } = options;
+  const base = parseRegularTableExport(schemaPath, name);
+  if (!base?.tableCall) {
+    throw new Error(
+      `[module-kit] Could not find a table export named "${name}" in "${schemaPath}". When "factory" is omitted, "schema" must be a regular drizzle file, e.g. \`export const ${name} = sqliteTable(${JSON.stringify(name)}, { ... })\`.`
+    );
+  }
+  const properties = new Map(base.properties);
+  const importsByModule = new Map([...base.imports].map(([module, specifiers]) => [module, new Set(specifiers)]));
+  for (const file of extensionFiles) {
+    const parsed = parseRegularTableExport(file, name);
+    if (!parsed) continue;
+    for (const [key, value] of parsed.properties) {
+      properties.delete(key);
+      properties.set(key, value);
+    }
+    for (const [module, specifiers] of parsed.imports) {
+      const set = importsByModule.get(module) ?? /* @__PURE__ */ new Set();
+      for (const specifier of specifiers) set.add(specifier);
+      importsByModule.set(module, set);
+    }
+  }
+  return addTemplate({
+    filename: `${name}/schema.${dialect}.ts`,
+    write: true,
+    getContents: () => `
+${[...importsByModule].map(([module, specifiers]) => `import { ${[...specifiers].join(", ")} } from ${JSON.stringify(module)}`).join("\n")}
+export const ${name} = ${base.tableCall.callee}(${JSON.stringify(base.tableCall.tableName)}, {
+${[...properties.values()].map((property) => `  ${property},`).join("\n")}
+})
+`
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frigear-nu/module-kit",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "private": false,
   "description": "Frigear Module Kit",
@@ -38,8 +38,10 @@
   ],
   "dependencies": {
     "@nuxt/kit": "^4.5.2",
+    "@nuxthub/core": "^0.10.8",
     "defu": "^6.1.7",
     "scule": "^1.3.0",
+    "typescript": "^6.0.3",
     "ufo": "^1.6.4",
     "zod": "^4.6.5"
   },
@@ -53,7 +55,6 @@
     "changelogen": "^0.6.2",
     "eslint": "^10.10.0",
     "nuxt": "^4.5.2",
-    "typescript": "^6.0.3",
     "vitest": "^5.0.1",
     "vue-tsc": "^3.3.11"
   },