@kubb/core 5.7.0 → 5.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -249,6 +249,10 @@ declare const diagnosticCode: {
249
249
  * A plugin's options are invalid, for example `output.mode: 'file'` paired with a `group` option.
250
250
  */
251
251
  readonly invalidPluginOptions: "KUBB_INVALID_PLUGIN_OPTIONS";
252
+ /**
253
+ * An extension's options fail its options `schema`.
254
+ */
255
+ readonly invalidOptions: "KUBB_INVALID_OPTIONS";
252
256
  /**
253
257
  * A post-generate command (`output.postGenerate`) exited with a failure.
254
258
  */
@@ -564,6 +568,7 @@ declare class Diagnostics {
564
568
  readonly pathTraversal: "KUBB_PATH_TRAVERSAL";
565
569
  readonly cleanRoot: "KUBB_CLEAN_ROOT";
566
570
  readonly invalidPluginOptions: "KUBB_INVALID_PLUGIN_OPTIONS";
571
+ readonly invalidOptions: "KUBB_INVALID_OPTIONS";
567
572
  readonly postGenerateFailed: "KUBB_POST_GENERATE_FAILED";
568
573
  readonly formatFailed: "KUBB_FORMAT_FAILED";
569
574
  readonly lintFailed: "KUBB_LINT_FAILED";
@@ -988,6 +993,45 @@ type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
988
993
  */
989
994
  declare function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement>;
990
995
  //#endregion
996
+ //#region src/standardSchema.d.ts
997
+ /**
998
+ * The parts of the Standard Schema v1 interfaces (https://standardschema.dev) that Kubb reads,
999
+ * copied as the spec recommends so core needs no schema library. Zod, Valibot and ArkType
1000
+ * schemas all match them.
1001
+ */
1002
+ interface StandardSchemaV1<Input = unknown, Output = Input> {
1003
+ readonly '~standard': StandardSchemaV1.Props<Input, Output>;
1004
+ }
1005
+ declare namespace StandardSchemaV1 {
1006
+ interface Props<Input = unknown, Output = Input> {
1007
+ readonly version: 1;
1008
+ readonly vendor: string;
1009
+ readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
1010
+ readonly types?: Types<Input, Output> | undefined;
1011
+ }
1012
+ type Result<Output> = SuccessResult<Output> | FailureResult;
1013
+ interface SuccessResult<Output> {
1014
+ readonly value: Output;
1015
+ readonly issues?: undefined;
1016
+ }
1017
+ interface FailureResult {
1018
+ readonly issues: ReadonlyArray<Issue>;
1019
+ }
1020
+ interface Issue {
1021
+ readonly message: string;
1022
+ readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
1023
+ }
1024
+ interface PathSegment {
1025
+ readonly key: PropertyKey;
1026
+ }
1027
+ interface Types<Input = unknown, Output = Input> {
1028
+ readonly input: Input;
1029
+ readonly output: Output;
1030
+ }
1031
+ type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
1032
+ type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
1033
+ }
1034
+ //#endregion
991
1035
  //#region src/defineExtension.d.ts
992
1036
  /**
993
1037
  * What an extension extends: a plugin generates code, an adapter reads the input, a parser prints files.
@@ -1066,10 +1110,14 @@ type ExtensionDependencyRecord = Partial<Record<PluginName, ExtensionDependency>
1066
1110
  /**
1067
1111
  * The function an extension definition returns. Call it with user options to get the extension.
1068
1112
  */
1069
- type ExtensionFactory<TKind extends ExtensionKind, TOptions, TExtension, TName extends string = string> = {
1113
+ type ExtensionFactory<TKind extends ExtensionKind, TOptions, TExtension, TName extends string = string, TParsedOptions = TOptions> = {
1070
1114
  (options?: TOptions): TExtension;
1071
1115
  kind: TKind;
1072
1116
  meta: ExtensionMeta<TName>;
1117
+ /**
1118
+ * The definition's options schema, so tools can read it without calling the factory.
1119
+ */
1120
+ schema?: StandardSchemaV1<TOptions, TParsedOptions>;
1073
1121
  };
1074
1122
  //#endregion
1075
1123
  //#region src/Resolver.d.ts
@@ -1639,16 +1687,30 @@ TResolvedOptions extends object = TOptions,
1639
1687
  * Resolver that encapsulates naming and path-resolution helpers.
1640
1688
  * Define with `createResolver` and export alongside the plugin.
1641
1689
  */
1642
- TResolver extends Resolver = Resolver> = {
1690
+ TResolver extends Resolver = Resolver,
1691
+ /**
1692
+ * Plugin options after the options `schema` parsed them, with its defaults applied.
1693
+ */
1694
+ TParsedOptions extends object = TOptions> = {
1643
1695
  name: TName;
1644
1696
  options: TOptions;
1697
+ parsedOptions: TParsedOptions;
1645
1698
  resolvedOptions: TResolvedOptions;
1646
1699
  resolver: TResolver;
1647
1700
  };
1701
+ type AsObject<T> = T extends object ? T : object;
1702
+ type InferOptionsInput<TOptions> = TOptions extends StandardSchemaV1 ? AsObject<StandardSchemaV1.InferInput<TOptions>> : TOptions;
1703
+ type InferOptionsOutput<TOptions> = TOptions extends StandardSchemaV1 ? AsObject<StandardSchemaV1.InferOutput<TOptions>> : TOptions;
1648
1704
  /**
1649
- * Type parameter for the object form of `definePlugin`. Same shape as `PluginFactoryOptions`.
1705
+ * Type parameter for the object form of `definePlugin`. Same shape as `PluginFactoryOptions`, except that
1706
+ * `TOptions` can also be the plugin's options schema. Then `options` is the schema's input type, and
1707
+ * `parsedOptions` and the default `resolvedOptions` are its output type.
1650
1708
  */
1651
- type PluginType<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions, TResolver extends Resolver = Resolver> = PluginFactoryOptions<TName, TOptions, TResolvedOptions, TResolver>;
1709
+ type PluginType<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = InferOptionsOutput<TOptions>, TResolver extends Resolver = Resolver> = PluginFactoryOptions<TName, InferOptionsInput<TOptions>, TResolvedOptions, TResolver, InferOptionsOutput<TOptions>>;
1710
+ /**
1711
+ * The options a user passes to a plugin with options schema `TSchema`: the schema's input type, before defaults apply.
1712
+ */
1713
+ type PluginOptions<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferInput<TSchema>;
1652
1714
  /**
1653
1715
  * Context passed to a plugin's `kubb:plugin:setup` handler, where it registers generators and
1654
1716
  * sets its resolver, transformer, and options.
@@ -1702,9 +1764,9 @@ type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactor
1702
1764
  */
1703
1765
  config: Config;
1704
1766
  /**
1705
- * The plugin's user-provided options.
1767
+ * The plugin's options, parsed by its options `schema` when it has one.
1706
1768
  */
1707
- options: TFactory['options'];
1769
+ options: TFactory['parsedOptions'];
1708
1770
  };
1709
1771
  /**
1710
1772
  * A plugin object produced by `definePlugin`. Its lifecycle handlers live under a single
@@ -1715,7 +1777,7 @@ type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = Exte
1715
1777
  * Plugins this one builds on. They run first when the config has them. An array only orders
1716
1778
  * plugins. A record also fails the run when a required entry is missing or out of range.
1717
1779
  */
1718
- dependencies?: Array<PluginName> | ExtensionDependencies<TFactory['options']>;
1780
+ dependencies?: Array<PluginName> | ExtensionDependencies<TFactory['parsedOptions']>;
1719
1781
  /**
1720
1782
  * Controls the execution order of this plugin relative to others.
1721
1783
  *
@@ -1730,6 +1792,10 @@ type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = Exte
1730
1792
  * The options passed by the user when calling the plugin factory.
1731
1793
  */
1732
1794
  options?: TFactory['options'];
1795
+ /**
1796
+ * The options after the plugin's options `schema` parsed them, with its defaults applied. Set only when the plugin has a `schema`.
1797
+ */
1798
+ parsedOptions?: TFactory['parsedOptions'];
1733
1799
  /**
1734
1800
  * Lifecycle hook handlers for this plugin.
1735
1801
  * Any hook from the global `KubbHooks` map can be subscribed to here.
@@ -1738,21 +1804,26 @@ type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = Exte
1738
1804
  'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>;
1739
1805
  };
1740
1806
  /**
1741
- * Runs before `kubb:plugin:setup`. Takes the user's options and returns the resolved options.
1807
+ * Runs before `kubb:plugin:setup`. Takes the parsed options and returns the resolved options.
1742
1808
  */
1743
- setup?(options: TFactory['options'], kubb: KubbPluginSetupContext<TFactory>): TFactory['resolvedOptions'] | Promise<TFactory['resolvedOptions']>;
1809
+ setup?(options: TFactory['parsedOptions'], kubb: KubbPluginSetupContext<TFactory>): TFactory['resolvedOptions'] | Promise<TFactory['resolvedOptions']>;
1744
1810
  };
1745
1811
  /**
1746
1812
  * The object passed to `definePlugin`.
1747
1813
  */
1748
1814
  type PluginDefinition<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = Pick<Plugin<TFactory>, 'dependencies' | 'enforce' | 'setup'> & {
1749
1815
  meta: ExtensionMeta<TFactory['name']>;
1816
+ /**
1817
+ * Any Standard Schema, such as a Zod schema, that validates the options and applies their defaults
1818
+ * when the factory is called. Invalid options throw `KUBB_INVALID_OPTIONS`. The schema must validate synchronously.
1819
+ */
1820
+ schema?: StandardSchemaV1<TFactory['options'], TFactory['parsedOptions']>;
1750
1821
  hooks?: Plugin<TFactory>['hooks'];
1751
1822
  };
1752
1823
  /**
1753
1824
  * The function `definePlugin` returns. Call it with user options to get a `Plugin`.
1754
1825
  */
1755
- type PluginFactory<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = ExtensionFactory<'plugin', TFactory['options'], Plugin<TFactory>, TFactory['name']>;
1826
+ type PluginFactory<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = ExtensionFactory<'plugin', TFactory['options'], Plugin<TFactory>, TFactory['name'], TFactory['parsedOptions']>;
1756
1827
  /**
1757
1828
  * Normalized plugin after setup, with runtime fields populated. Internal only. Plugins use the
1758
1829
  * public `Plugin` type.
@@ -1785,7 +1856,8 @@ type KubbPluginEndContext = FilesContext & {
1785
1856
  };
1786
1857
  /**
1787
1858
  * Defines a plugin from one object and returns a factory that takes the user's options.
1788
- * Name plugins `plugin-<feature>`.
1859
+ * Name plugins `plugin-<feature>`. Set `schema` to validate the options and apply their defaults
1860
+ * before `setup` receives them.
1789
1861
  *
1790
1862
  * @example
1791
1863
  * ```ts
@@ -3029,5 +3101,5 @@ type BuildOutput = {
3029
3101
  storage: Storage;
3030
3102
  };
3031
3103
  //#endregion
3032
- export { OutputOptions as $, SerializedDiagnostic as $t, HookResult as A, resolveMeta as At, ParserDefinition as B, ReporterPluginFiles as Bt, KubbMessageContext as C, ResolverPathParams as Ct, PossibleConfig as D, ExtensionFactory as Dt, KubbWarnContext as E, ExtensionDependencyRecord as Et, defineGenerator as F, createStorage as Ft, Group as G, DiagnosticDoc as Gt, defineParser as H, createReporter as Ht, NodeCache as I, GenerationResult as It, KubbPluginSetupContext as J, DiagnosticSeverity as Jt, Include as K, DiagnosticKind as Kt, KubbDriver as L, Reporter as Lt, runHook as M, RendererFactory as Mt, Generator as N, createRenderer as Nt, PostGenerateCommand as O, ExtensionKind as Ot, GeneratorContext as P, Storage as Pt, OutputMode as Q, ProblemDiagnostic as Qt, FileManagerHooks as R, ReporterContext as Rt, KubbLifecycleStartContext as S, ResolverPatch as St, KubbSuccessContext as T, ExtensionDependency as Tt, Exclude$1 as U, logLevel as Ut, ParserFactory as V, UserReporter as Vt, Filter as W, Diagnostic as Wt, NormalizedPlugin as X, PerformanceDiagnostic as Xt, KubbPluginStartContext as Y, Diagnostics as Yt, Output as Z, ProblemCode as Zt, KubbHookEndContext as _, Resolver as _t, Input as a, createAdapter as an, PluginName as at, KubbHooks as b, ResolverFileParams as bt, KubbDiagnosticContext as c, assertPluginOption as ct, KubbFilesProcessingEndContext as d, ResolveBannerContext as dt, UpdateDiagnostic as en, Override as et, KubbFilesProcessingStartContext as f, ResolveBannerFile as ft, KubbGenerationSummaryContext as g, ResolvePathOptions as gt, KubbGenerationStartContext as h, ResolveOptionsContext as ht, FilesContext as i, AdapterSource as in, PluginFactoryOptions as it, RunHookOptions as j, Renderer as jt, UserConfig as k, ExtensionMeta as kt, KubbErrorContext as l, definePlugin as lt, KubbGenerationEndContext as m, ResolveImportsOptions as mt, CLIOptions as n, Adapter as nn, PluginDefinition as nt, KubbBuildEndContext as o, PluginType as ot, KubbFilesProcessingUpdateContext as p, ResolveFileOptions as pt, KubbPluginEndContext as q, DiagnosticLocation as qt, Config as r, AdapterFactoryOptions as rn, PluginFactory as rt, KubbBuildStartContext as s, ResolvePluginOptions as st, BuildOutput as t, Hookable as tn, Plugin as tt, KubbFileProcessingUpdate as u, BannerMeta as ut, KubbHookLineContext as v, ResolverDefault as vt, KubbPluginsEndContext as w, ExtensionDependencies as wt, KubbInfoContext as x, ResolverFilePathParams as xt, KubbHookStartContext as y, ResolverFile as yt, Parser as z, ReporterName as zt };
3033
- //# sourceMappingURL=types-Cd91JYuu.d.ts.map
3104
+ export { OutputOptions as $, ProblemCode as $t, HookResult as A, ExtensionMeta as At, ParserDefinition as B, ReporterContext as Bt, KubbMessageContext as C, ResolverPatch as Ct, PossibleConfig as D, ExtensionDependencyRecord as Dt, KubbWarnContext as E, ExtensionDependency as Et, defineGenerator as F, createRenderer as Ft, Group as G, logLevel as Gt, defineParser as H, ReporterPluginFiles as Ht, NodeCache as I, Storage as It, KubbPluginSetupContext as J, DiagnosticKind as Jt, Include as K, Diagnostic as Kt, KubbDriver as L, createStorage as Lt, runHook as M, StandardSchemaV1 as Mt, Generator as N, Renderer as Nt, PostGenerateCommand as O, ExtensionFactory as Ot, GeneratorContext as P, RendererFactory as Pt, OutputMode as Q, PerformanceDiagnostic as Qt, FileManagerHooks as R, GenerationResult as Rt, KubbLifecycleStartContext as S, ResolverFilePathParams as St, KubbSuccessContext as T, ExtensionDependencies as Tt, Exclude$1 as U, UserReporter as Ut, ParserFactory as V, ReporterName as Vt, Filter as W, createReporter as Wt, NormalizedPlugin as X, DiagnosticSeverity as Xt, KubbPluginStartContext as Y, DiagnosticLocation as Yt, Output as Z, Diagnostics as Zt, KubbHookEndContext as _, ResolvePathOptions as _t, Input as a, AdapterFactoryOptions as an, PluginName as at, KubbHooks as b, ResolverFile as bt, KubbDiagnosticContext as c, ResolvePluginOptions as ct, KubbFilesProcessingEndContext as d, BannerMeta as dt, ProblemDiagnostic as en, Override as et, KubbFilesProcessingStartContext as f, ResolveBannerContext as ft, KubbGenerationSummaryContext as g, ResolveOptionsContext as gt, KubbGenerationStartContext as h, ResolveImportsOptions as ht, FilesContext as i, Adapter as in, PluginFactoryOptions as it, RunHookOptions as j, resolveMeta as jt, UserConfig as k, ExtensionKind as kt, KubbErrorContext as l, assertPluginOption as lt, KubbGenerationEndContext as m, ResolveFileOptions as mt, CLIOptions as n, UpdateDiagnostic as nn, PluginDefinition as nt, KubbBuildEndContext as o, AdapterSource as on, PluginOptions as ot, KubbFilesProcessingUpdateContext as p, ResolveBannerFile as pt, KubbPluginEndContext as q, DiagnosticDoc as qt, Config as r, Hookable as rn, PluginFactory as rt, KubbBuildStartContext as s, createAdapter as sn, PluginType as st, BuildOutput as t, SerializedDiagnostic as tn, Plugin as tt, KubbFileProcessingUpdate as u, definePlugin as ut, KubbHookLineContext as v, Resolver as vt, KubbPluginsEndContext as w, ResolverPathParams as wt, KubbInfoContext as x, ResolverFileParams as xt, KubbHookStartContext as y, ResolverDefault as yt, Parser as z, Reporter as zt };
3105
+ //# sourceMappingURL=types-anBcq2U0.d.ts.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubb/core",
3
- "version": "5.7.0",
3
+ "version": "5.8.0",
4
4
  "description": "Core engine for Kubb. Provides the plugin driver, file manager and build orchestration used by every Kubb plugin.",
5
5
  "keywords": [
6
6
  "code-generator",
@@ -72,7 +72,7 @@
72
72
  "registry": "https://registry.npmjs.org/"
73
73
  },
74
74
  "dependencies": {
75
- "@kubb/ast": "5.7.0",
75
+ "@kubb/ast": "5.8.0",
76
76
  "tinyexec": "^1.3.1",
77
77
  "unstorage": "^1.17.5",
78
78
  "verkit": "^0.5.0"