@nanokajs/core 0.1.4 → 1.0.1

package/dist/index.d.ts

@@ -1,37 +1,14 @@
 import { D1Database } from '@cloudflare/workers-types';
-import { BatchItem, BatchResponse } from 'drizzle-orm/batch';
-import { BaseSQLiteDatabase, SQLiteTable } from 'drizzle-orm/sqlite-core';
-import { F as Field, I as InferFieldType } from './factories-CDsk1Hdt.js';
-export { a as FieldModifiers, t } from './factories-CDsk1Hdt.js';
+import { A as Adapter } from './types-D2QDVyks.js';
+import { F as Field, I as InferFieldType, a as FieldPolicy } from './factories-Cmvx0495.js';
+export { b as FieldModifiers, t } from './factories-Cmvx0495.js';
 import { Hook } from '@hono/zod-validator';
+import { SQLiteTable } from 'drizzle-orm/sqlite-core';
 import * as hono from 'hono';
 import { ValidationTargets, Env, MiddlewareHandler, Hono } from 'hono';
 import { z } from 'zod';
 import { Env as Env$1, BlankEnv } from 'hono/types';
-
-/**
- * Generic database adapter abstraction for SQLite-compatible databases.
- *
- * Permits implementations over D1, Turso/libSQL, and other SQLite-compatible backends
- * without requiring changes to core query path or router.
- *
- * The `drizzle` property deliberately exposes the raw Drizzle database instance,
- * adhering to rule #4 (escape hatch always open).
- *
- * The `TResultKind` generic is intentionally constrained to `any` to avoid
- * coupling adapter implementations to Drizzle's internal result kind type.
- */
-interface Adapter<TSchema extends Record<string, unknown> = Record<string, never>> {
-    readonly drizzle: BaseSQLiteDatabase<'async', any, TSchema>;
-    /**
-     * Executes multiple Drizzle queries in a single batch.
-     * Returns results in the same order as the input.
-     *
-     * **重要**: 実装は `this` 非依存であること（`nanoka()` 内で thin wrapper として再公開されるため、
-     * `this` バインディングが失われた状態で呼び出される可能性がある）。
-     */
-    batch<U extends BatchItem<'sqlite'>, T extends readonly [U, ...U[]]>(queries: T): Promise<BatchResponse<T>>;
-}
+import 'drizzle-orm/batch';
 
 /**
  * D1-specific adapter factory. Wraps Cloudflare D1 binding in the generic
@@ -40,6 +17,67 @@ interface Adapter<TSchema extends Record<string, unknown> = Record<string, never
  */
 declare function d1Adapter<TSchema extends Record<string, unknown> = Record<string, never>>(d1: D1Database): Adapter<TSchema>;
 
+type OpenAPISchemaObject = Record<string, unknown>;
+interface OpenAPIModelComponent {
+    create: OpenAPISchemaObject;
+    update: OpenAPISchemaObject;
+    output: OpenAPISchemaObject;
+}
+type OpenAPIUsage = 'create' | 'update' | 'output';
+type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+interface OpenAPIRequestBodySpec {
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly content: {
+        readonly 'application/json': {
+            readonly schema: OpenAPISchemaObject;
+        };
+    };
+}
+interface OpenAPIResponseSpec {
+    readonly description: string;
+    readonly content?: {
+        readonly 'application/json': {
+            readonly schema: OpenAPISchemaObject;
+        };
+    };
+}
+interface OpenAPIParamSpec {
+    readonly name: string;
+    readonly in: 'path' | 'query' | 'header';
+    readonly required?: boolean;
+    readonly schema: OpenAPISchemaObject;
+    readonly description?: string;
+}
+interface OpenAPIRouteMetadata {
+    readonly path: string;
+    readonly method: HttpMethod;
+    readonly operationId?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly requestBody?: OpenAPIRequestBodySpec;
+    readonly params?: OpenAPIParamSpec[];
+    readonly responses: Record<string, OpenAPIResponseSpec>;
+}
+interface OpenAPISpecOptions {
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description?: string;
+    };
+    readonly servers?: ReadonlyArray<{
+        readonly url: string;
+        readonly description?: string;
+    }>;
+}
+interface OpenAPIDocument {
+    readonly openapi: '3.1.0';
+    readonly info: OpenAPISpecOptions['info'];
+    readonly servers?: OpenAPISpecOptions['servers'];
+    readonly paths: Record<string, Record<string, unknown>>;
+}
+
 /**
  * Options for findMany query.
  * `limit` is required (no default).
@@ -78,13 +116,84 @@ type RowType<Fields extends Record<string, Field<any, any, any>>> = {
     [K in keyof Fields]: InferFieldType<Fields[K]>;
 };
 /**
- * Create input: partial row (most fields optional for insert).
- * Phase 1 では `Partial<RowType>` のままとし、必須/任意フィールドの型区別は Phase 2 で扱う。
+ * @internal
+ * Extracts the policy from a Field's modifiers.
+ *
+ * Uses `Field<any, { policy: infer P }, any>` rather than a two-step
+ * `infer M` + `M extends { policy: infer P }` pattern.
+ * The two-step pattern is broken when TypeScript widens `M` to the constraint
+ * `FieldModifiers` (which has `policy?: FieldPolicy` as optional), causing
+ * `M extends { policy: infer P }` to be true for ALL fields regardless of their
+ * actual policy value. Directly matching `{ policy: infer P }` avoids this.
+ */
+type PolicyOf<F> = F extends Field<any, {
+    policy: infer P extends FieldPolicy;
+}, any> ? P : never;
+/**
+ * @internal
+ * Computes which field keys should be omitted based on policy and usage.
+ * Mirrors the runtime logic in derivePolicyOptions() in schema.ts.
+ *
+ * NOTE: `[PolicyOf<Fields[K]>] extends [never]` (non-distributive form) is used to
+ * short-circuit fields with no policy to `never` (do not omit). Without this guard,
+ * `never extends 'serverOnly'` evaluates to `true` (vacuously), causing every field
+ * without a policy to be incorrectly included in the omit set.
+ */
+type PolicyOmitKeys<Fields extends Record<string, Field<any, any, any>>, Usage extends 'input-create' | 'input-update' | 'output'> = {
+    [K in keyof Fields]: [PolicyOf<Fields[K]>] extends [never] ? never : PolicyOf<Fields[K]> extends 'serverOnly' ? K : Usage extends 'output' ? PolicyOf<Fields[K]> extends 'writeOnly' ? K : never : Usage extends 'input-create' | 'input-update' ? PolicyOf<Fields[K]> extends 'readOnly' ? K : never : never;
+}[keyof Fields];
+/**
+ * @internal
+ * Computes which field keys have the serverOnly policy.
+ * serverOnly fields are completely excluded from CreateInput
+ * (cannot be passed even from library internals — they are server-side only).
+ *
+ * Uses `[PolicyOf<Fields[K]>] extends [never]` (non-distributive form) to short-circuit
+ * fields with no policy to `never`. Without this guard, `never extends 'serverOnly'`
+ * evaluates to `true` (vacuously), causing every field without a policy to be included.
  */
-type CreateInput<Fields extends Record<string, Field<any, any, any>>> = Partial<RowType<Fields>>;
+type ServerOnlyKeys<Fields extends Record<string, Field<any, any, any>>> = {
+    [K in keyof Fields]: [PolicyOf<Fields[K]>] extends [never] ? never : PolicyOf<Fields[K]> extends 'serverOnly' ? K : never;
+}[keyof Fields];
+/**
+ * @internal
+ * Determines if a field is required for create input.
+ * A field is optional if it has a default, is optional, or is readOnly.
+ *
+ * Uses direct shape matching (`Field<any, { hasDefault: true }, any>`) to avoid
+ * the TypeScript infer-widening issue where `infer M` resolves to `FieldModifiers`
+ * (the constraint bound) instead of the concrete Mods type, causing `M extends
+ * { policy: 'readOnly' }` to be false even for readOnly fields.
+ */
+type IsRequired<F extends Field<any, any, any>> = F extends Field<any, {
+    hasDefault: true;
+}, any> ? false : F extends Field<any, {
+    optional: true;
+}, any> ? false : F extends Field<any, {
+    policy: 'readOnly';
+}, any> ? false : true;
+/**
+ * Create input with precise types:
+ * - `readOnly` fields are optional (library internals can pass them; API callers
+ *   are excluded via inputSchema — but CreateInput itself keeps them as optional
+ *   so handlers can supply generated values like `id` or `createdAt`)
+ * - fields with `default` are optional
+ * - fields marked `optional` are optional
+ * - all other fields are required
+ * - `serverOnly` fields are completely excluded (cannot be passed even internally)
+ * - `writeOnly` fields are included as required (they are input fields by design)
+ */
+type CreateInput<Fields extends Record<string, Field<any, any, any>>> = {
+    [K in keyof Fields as IsRequired<Fields[K]> extends true ? K extends ServerOnlyKeys<Fields> ? never : K : never]: InferFieldType<Fields[K]>;
+} & {
+    [K in keyof Fields as IsRequired<Fields[K]> extends true ? never : K extends ServerOnlyKeys<Fields> ? never : K]?: InferFieldType<Fields[K]>;
+};
+type FieldAccessor<K extends string> = {
+    readonly [Key in K]: Key;
+};
 interface SchemaOptions<K extends string = string> {
-    readonly pick?: readonly K[];
-    readonly omit?: readonly K[];
+    readonly pick?: readonly K[] | ((f: FieldAccessor<K>) => readonly K[]);
+    readonly omit?: readonly K[] | ((f: FieldAccessor<K>) => readonly K[]);
     readonly partial?: boolean;
 }
 /**
@@ -101,16 +210,22 @@ type FieldsToZodShape<Fields extends Record<string, Field<any, any, any>>> = {
  * Utility to narrow array literal types to union of strings.
  */
 type ArrayKeys<A> = A extends readonly (infer U)[] ? U : never;
+/**
+ * @internal
+ * Resolves pick/omit option type to the array type.
+ * Handles both array form and accessor function form.
+ */
+type ResolveOptKeys<Opt> = Opt extends readonly string[] ? Opt : Opt extends (f: FieldAccessor<infer _K>) => readonly (infer R)[] ? readonly R[] : never;
 /**
  * @internal
  * Apply pick transformation to a shape.
  */
-type ApplyPickToShape<Shape extends z.ZodRawShape, PickKeys> = PickKeys extends readonly string[] ? Pick<Shape, ArrayKeys<PickKeys> & keyof Shape> : Shape;
+type ApplyPickToShape<Shape extends z.ZodRawShape, PickOpt> = ResolveOptKeys<PickOpt> extends readonly string[] ? Pick<Shape, ArrayKeys<ResolveOptKeys<PickOpt>> & keyof Shape> : Shape;
 /**
  * @internal
  * Apply omit transformation to a shape.
  */
-type ApplyOmitToShape<Shape extends z.ZodRawShape, OmitKeys> = OmitKeys extends readonly string[] ? Omit<Shape, ArrayKeys<OmitKeys> & keyof Shape> : Shape;
+type ApplyOmitToShape<Shape extends z.ZodRawShape, OmitOpt> = ResolveOptKeys<OmitOpt> extends readonly string[] ? Omit<Shape, ArrayKeys<ResolveOptKeys<OmitOpt>> & keyof Shape> : Shape;
 /**
  * @internal
  * Apply partial transformation to a shape.
@@ -118,38 +233,77 @@ type ApplyOmitToShape<Shape extends z.ZodRawShape, OmitKeys> = OmitKeys extends
 type ApplyPartialToShape<Shape extends z.ZodRawShape> = {
     [K in keyof Shape]: z.ZodOptional<Shape[K]>;
 };
+/**
+ * @internal
+ * Checks if an option value (array or function) is present (i.e. not undefined and not never).
+ * Uses distributive conditional to handle union types like `T | undefined`.
+ */
+type HasOpt<Opt> = undefined extends Opt ? false : [Opt] extends [never] ? false : true;
 /**
  * @internal
  * Apply pick/omit/partial transformations to a Zod raw shape.
  * Order: pick → omit → partial
+ * Handles both array form and accessor function form for pick/omit.
  */
-type ApplyShape<Shape extends z.ZodRawShape, Opts extends SchemaOptions | undefined> = Opts extends undefined ? Shape : Opts extends {
-    pick: readonly string[];
-} ? Opts extends {
-    omit: readonly string[];
-} ? Opts extends {
+type ApplyShape<Shape extends z.ZodRawShape, Opts extends SchemaOptions | undefined> = Opts extends SchemaOptions ? HasOpt<Opts['pick']> extends true ? HasOpt<Opts['omit']> extends true ? Opts extends {
     partial: true;
 } ? ApplyPartialToShape<ApplyOmitToShape<ApplyPickToShape<Shape, Opts['pick']>, Opts['omit']>> : ApplyOmitToShape<ApplyPickToShape<Shape, Opts['pick']>, Opts['omit']> : Opts extends {
     partial: true;
-} ? ApplyPartialToShape<ApplyPickToShape<Shape, Opts['pick']>> : ApplyPickToShape<Shape, Opts['pick']> : Opts extends {
-    omit: readonly string[];
-} ? Opts extends {
+} ? ApplyPartialToShape<ApplyPickToShape<Shape, Opts['pick']>> : ApplyPickToShape<Shape, Opts['pick']> : HasOpt<Opts['omit']> extends true ? Opts extends {
     partial: true;
 } ? ApplyPartialToShape<ApplyOmitToShape<Shape, Opts['omit']>> : ApplyOmitToShape<Shape, Opts['omit']> : Opts extends {
     partial: true;
-} ? ApplyPartialToShape<Shape> : Shape;
+} ? ApplyPartialToShape<Shape> : Shape : Shape;
 /**
  * @internal
  * Returns the correct Zod object type after applying pick/omit/partial transformations.
  */
 type Apply<Shape extends z.ZodRawShape, Opts extends SchemaOptions | undefined> = z.ZodObject<ApplyShape<Shape, Opts>>;
+/**
+ * @internal
+ * Apply pick transformation to a TS record type.
+ */
+type ApplyPickToRecord<R, PickOpt> = ResolveOptKeys<PickOpt> extends readonly string[] ? Pick<R, ArrayKeys<ResolveOptKeys<PickOpt>> & keyof R> : R;
+/**
+ * @internal
+ * Apply omit transformation to a TS record type.
+ */
+type ApplyOmitToRecord<R, OmitOpt> = ResolveOptKeys<OmitOpt> extends readonly string[] ? Omit<R, ArrayKeys<ResolveOptKeys<OmitOpt>> & keyof R> : R;
+/**
+ * @internal
+ * Apply pick/omit/partial transformations to a TypeScript record type.
+ * Mirrors ApplyShape but operates on TS types directly, not Zod shapes.
+ * Used for Zod v3/v4 compatible middleware input/output type computation.
+ */
+type ApplyToRecord<R, Opts extends SchemaOptions | undefined> = Opts extends SchemaOptions ? HasOpt<Opts['pick']> extends true ? HasOpt<Opts['omit']> extends true ? Opts extends {
+    partial: true;
+} ? Partial<ApplyOmitToRecord<ApplyPickToRecord<R, Opts['pick']>, Opts['omit']>> : ApplyOmitToRecord<ApplyPickToRecord<R, Opts['pick']>, Opts['omit']> : Opts extends {
+    partial: true;
+} ? Partial<ApplyPickToRecord<R, Opts['pick']>> : ApplyPickToRecord<R, Opts['pick']> : HasOpt<Opts['omit']> extends true ? Opts extends {
+    partial: true;
+} ? Partial<ApplyOmitToRecord<R, Opts['omit']>> : ApplyOmitToRecord<R, Opts['omit']> : Opts extends {
+    partial: true;
+} ? Partial<R> : R : R;
 /**
  * @internal
  * Mirrors @hono/zod-validator's middleware Input type.
  * Aligned with @hono/zod-validator@0.4.x; revisit on version bump.
  */
 type HasUndefined<T> = undefined extends T ? true : false;
-type ValidatorInput<Target extends keyof ValidationTargets, Schema extends z.ZodType<any, z.ZodTypeDef, any>, In = z.input<Schema>, Out = z.output<Schema>> = {
+/**
+ * @internal
+ * Hono middleware input/output type for validator middleware.
+ * Aligned with @hono/zod-validator@0.4.x; revisit on version bump.
+ *
+ * WARNING (Zod 4): `z.input<ZodTypeAny>` resolves to `unknown` in Zod 4, making
+ * `c.req.valid(target)` return `unknown` if `In`/`Out` are left as defaults.
+ * When using this type directly (outside of `ModelValidatorReturn`), always pass
+ * explicit `In` and `Out` type arguments — do NOT rely on the defaults.
+ *
+ * Internal usages in this file (ModelValidatorReturn and preset overloads) already
+ * pass `In`/`Out` explicitly via `ApplyToRecord` or `Omit<RowType<Fields>, ...>`.
+ */
+type ValidatorInput<Target extends keyof ValidationTargets, Schema extends z.ZodTypeAny, In = z.input<Schema>, Out = z.output<Schema>> = {
     in: HasUndefined<In> extends true ? {
         [K in Target]?: (In extends ValidationTargets[K] ? In : {
             [K2 in keyof In]?: ValidationTargets[K][K2] | undefined;
@@ -167,8 +321,11 @@ type ValidatorInput<Target extends keyof ValidationTargets, Schema extends z.Zod
  * @internal
  * Type-safe Hono middleware handler return for Model.validator().
  * Provides proper type narrowing for c.req.valid(target).
+ *
+ * Uses RowType<Fields> directly for input/output type computation
+ * to ensure Zod v3/v4 compatibility (z.input<ZodTypeAny> returns unknown in Zod v4).
  */
-type ModelValidatorReturn<Fields extends Record<string, Field<any, any, any>>, Target extends keyof ValidationTargets, Opts extends SchemaOptions<keyof Fields & string> | undefined> = MiddlewareHandler<any, string, ValidatorInput<Target, Apply<FieldsToZodShape<Fields>, Opts>>>;
+type ModelValidatorReturn<Fields extends Record<string, Field<any, any, any>>, Target extends keyof ValidationTargets, Opts extends SchemaOptions<keyof Fields & string> | undefined> = MiddlewareHandler<any, string, ValidatorInput<Target, Apply<FieldsToZodShape<Fields>, Opts>, ApplyToRecord<RowType<Fields>, Opts>, ApplyToRecord<RowType<Fields>, Opts>>>;
 
 /**
  * Represents a database model with type-safe schema derivation and CRUD operations.
@@ -185,22 +342,60 @@ interface Model<Fields extends Record<string, Field<any, any, any>>> {
      * const CreateSchema = User.schema({ omit: ['passwordHash'] })
      * const UpdateSchema = User.schema({ partial: true, pick: ['name', 'email'] })
      */
-    schema<Opts extends SchemaOptions<keyof Fields & string> | undefined = undefined>(opts?: Opts): Apply<FieldsToZodShape<Fields>, Opts>;
+    schema<Opts extends SchemaOptions<keyof Fields & string> | undefined>(opts?: Opts): Apply<FieldsToZodShape<Fields>, Opts>;
     /**
      * Returns a Hono middleware validator derived from this model's schema.
      * Integrates with @hono/zod-validator to validate request inputs.
      * The optional `hook` argument is passed through to @hono/zod-validator.
      *
+     * Accepts a preset ('create' | 'update') as second argument to use inputSchema.
+     * When a preset is used, the return type is a MiddlewareHandler (loosely typed in Phase 2A).
+     * Precise type narrowing for preset is deferred to Phase 2B M2.3.
+     *
      * @example
+     * app.post('/users', User.validator('json', 'create'), c => {
+     *   const body = c.req.valid('json')
+     * })
      * app.post('/users', User.validator('json', { omit: ['passwordHash'] }), c => {
      *   const body = c.req.valid('json')
      * })
-     * // With hook for hardened error responses:
+     * // With hook:
      * app.post('/users', User.validator('json', opts, (result, c) => {
      *   if (!result.success) return c.json({ error: 'Invalid request' }, 400)
      * }), handler)
      */
-    validator<Target extends keyof ValidationTargets, Opts extends SchemaOptions<keyof Fields & string> | undefined = undefined, E extends Env = Env, P extends string = string>(target: Target, opts?: Opts, hook?: Hook<z.output<Apply<FieldsToZodShape<Fields>, Opts>>, E, P, Target>): ModelValidatorReturn<Fields, Target, Opts>;
+    validator<Target extends keyof ValidationTargets, E extends Env = Env, P extends string = string>(target: Target, preset: 'create', hook?: Hook<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-create'> & string>, E, P, Target>): MiddlewareHandler<E, P, ValidatorInput<Target, z.ZodObject<z.ZodRawShape>, Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-create'> & string>, Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-create'> & string>>>;
+    validator<Target extends keyof ValidationTargets, E extends Env = Env, P extends string = string>(target: Target, preset: 'update', hook?: Hook<Partial<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-update'> & string>>, E, P, Target>): MiddlewareHandler<E, P, ValidatorInput<Target, z.ZodObject<z.ZodRawShape>, Partial<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-update'> & string>>, Partial<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-update'> & string>>>>;
+    validator<Target extends keyof ValidationTargets, Opts extends SchemaOptions<keyof Fields & string> | undefined, E extends Env = Env, P extends string = string>(target: Target, opts?: Opts, hook?: Hook<z.output<Apply<FieldsToZodShape<Fields>, Opts>>, E, P, Target>): ModelValidatorReturn<Fields, Target, Opts>;
+    /**
+     * Returns a Zod schema for API input, with policy-based field exclusions applied.
+     * - 'create': serverOnly and readOnly fields are excluded
+     * - 'update': same exclusions + all fields become optional (partial: true)
+     *
+     * The return type precisely reflects policy-derived omissions using PolicyOmitKeys.
+     */
+    inputSchema<Opts extends SchemaOptions<keyof Fields & string> | undefined = undefined>(usage: 'create', opts?: Opts): z.ZodObject<ApplyShape<Omit<FieldsToZodShape<Fields>, PolicyOmitKeys<Fields, 'input-create'> & string>, Opts>>;
+    inputSchema<Opts extends SchemaOptions<keyof Fields & string> | undefined = undefined>(usage: 'update', opts?: Opts): z.ZodObject<ApplyShape<Omit<FieldsToZodShape<Fields>, PolicyOmitKeys<Fields, 'input-update'> & string>, Opts extends undefined ? {
+        partial: true;
+    } : Opts & {
+        partial: true;
+    }>>;
+    inputSchema(usage: 'create' | 'update', opts?: SchemaOptions<keyof Fields & string>): z.ZodObject<z.ZodRawShape>;
+    /**
+     * Returns a Zod schema for API output, with policy-based field exclusions applied.
+     * - serverOnly and writeOnly fields are excluded
+     * - readOnly fields remain present
+     *
+     * The return type precisely reflects policy-derived omissions using PolicyOmitKeys.
+     */
+    outputSchema<Opts extends SchemaOptions<keyof Fields & string> | undefined = undefined>(opts?: Opts): z.ZodObject<ApplyShape<Omit<FieldsToZodShape<Fields>, PolicyOmitKeys<Fields, 'output'> & string>, Opts>>;
+    /**
+     * Parses a DB row through outputSchema and returns the safe response object.
+     * Equivalent to `User.outputSchema().parse(row)`.
+     */
+    toResponse(row: RowType<Fields>): unknown;
+    toOpenAPIComponent(): OpenAPIModelComponent;
+    toOpenAPISchema(usage: OpenAPIUsage): OpenAPISchemaObject;
     /**
      * Fetches multiple rows with pagination and optional ordering.
      * `limit` is required (no default) to prevent accidental unbounded queries.
@@ -250,6 +445,12 @@ interface Model<Fields extends Record<string, Field<any, any, any>>> {
     }>;
 }
 
+interface SwaggerUIOptions {
+    readonly url: string;
+    readonly title?: string;
+}
+declare function swaggerUI(options: SwaggerUIOptions): MiddlewareHandler;
+
 /**
  * Creates a Model instance from a tableName and fields definition.
  * The model supports deriving Zod schemas, Hono validators, and CRUD operations.
@@ -286,8 +487,25 @@ interface NanokaModel<Fields extends Record<string, Field<any, any, any>>> {
     /**
      * Returns a Hono middleware validator for this model.
      * The optional `hook` argument is passed through to @hono/zod-validator.
+     * Accepts a preset ('create' | 'update') as second argument to use inputSchema.
      */
+    validator<Target extends keyof hono.ValidationTargets, E extends Env$1 = Env$1, P extends string = string>(target: Target, preset: 'create', hook?: Hook<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-create'> & string>, E, P, Target>): MiddlewareHandler<E, P, ValidatorInput<Target, z.ZodObject<z.ZodRawShape>, Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-create'> & string>, Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-create'> & string>>>;
+    validator<Target extends keyof hono.ValidationTargets, E extends Env$1 = Env$1, P extends string = string>(target: Target, preset: 'update', hook?: Hook<Partial<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-update'> & string>>, E, P, Target>): MiddlewareHandler<E, P, ValidatorInput<Target, z.ZodObject<z.ZodRawShape>, Partial<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-update'> & string>>, Partial<Omit<RowType<Fields>, PolicyOmitKeys<Fields, 'input-update'> & string>>>>;
     validator<Target extends keyof hono.ValidationTargets, Opts extends SchemaOptions<keyof Fields & string> | undefined = undefined, E extends Env$1 = Env$1, P extends string = string>(target: Target, opts?: Opts, hook?: Hook<z.output<Apply<FieldsToZodShape<Fields>, Opts>>, E, P, Target>): ModelValidatorReturn<Fields, Target, Opts>;
+    /**
+     * Returns a Zod schema for API input, with policy-based field exclusions applied.
+     */
+    inputSchema(usage: 'create' | 'update', opts?: SchemaOptions<keyof Fields & string>): z.ZodObject<z.ZodRawShape>;
+    /**
+     * Returns a Zod schema for API output, with policy-based field exclusions applied.
+     */
+    outputSchema(opts?: SchemaOptions<keyof Fields & string>): z.ZodObject<z.ZodRawShape>;
+    /**
+     * Parses a DB row through outputSchema and returns the safe response object.
+     */
+    toResponse(row: RowType<Fields>): unknown;
+    toOpenAPIComponent(): OpenAPIModelComponent;
+    toOpenAPISchema(usage: OpenAPIUsage): OpenAPISchemaObject;
     /**
      * Fetches multiple rows with pagination and optional ordering.
      * `limit` is required (no default) to prevent accidental unbounded queries.
@@ -341,6 +559,15 @@ interface Nanoka<E extends Env$1 = BlankEnv> extends Hono<E> {
      * const users = await User.findMany({ limit: 20 })
      */
     model<Fields extends Record<string, Field<any, any, any>>>(name: string, fields: Fields): NanokaModel<Fields>;
+    /**
+     * Registers OpenAPI metadata for a route.
+     * Does NOT register the actual Hono handler — call app.get/post/... separately.
+     */
+    openapi(metadata: OpenAPIRouteMetadata): this;
+    /**
+     * Builds the full OpenAPI 3.1 document from all registered openapi() metadata.
+     */
+    generateOpenAPISpec(options: OpenAPISpecOptions): OpenAPIDocument;
 }
 
 /**
@@ -364,4 +591,4 @@ interface Nanoka<E extends Env$1 = BlankEnv> extends Hono<E> {
  */
 declare function nanoka<E extends Env$1 = BlankEnv>(adapter: Adapter): Nanoka<E>;
 
-export { type Adapter, type CreateInput, Field, type FindManyOptions, type IdOrWhere, InferFieldType, type Model, type Nanoka, type NanokaModel, type OrderBy, type RowType, type SchemaOptions, type Where, d1Adapter, defineModel, nanoka };
+export { Adapter, type CreateInput, Field, FieldPolicy, type FindManyOptions, type HttpMethod, type IdOrWhere, InferFieldType, type Model, type Nanoka, type NanokaModel, type OpenAPIDocument, type OpenAPIModelComponent, type OpenAPIParamSpec, type OpenAPIRequestBodySpec, type OpenAPIResponseSpec, type OpenAPIRouteMetadata, type OpenAPISchemaObject, type OpenAPISpecOptions, type OpenAPIUsage, type OrderBy, type RowType, type SchemaOptions, type Where, d1Adapter, defineModel, nanoka, swaggerUI };