@apinni/client-ts 0.0.0 → 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,409 @@
+import { Type, Node, Decorator } from 'ts-morph';
+
+type JsonSchemaType = 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array' | 'enum' | 'ref' | 'never' | 'complex' | 'any' | 'undefined';
+interface SchemaDefinitionProperties {
+    global?: string;
+    description?: string;
+    example?: string;
+    default?: string;
+    deprecated?: string;
+}
+interface BaseJsonSchema extends SchemaDefinitionProperties {
+    type: JsonSchemaType;
+}
+interface StringSchema extends BaseJsonSchema {
+    type: 'string';
+    const?: string;
+}
+interface NumberSchema extends BaseJsonSchema {
+    type: 'number';
+    const?: number;
+}
+interface BooleanSchema extends BaseJsonSchema {
+    type: 'boolean';
+    const?: boolean;
+}
+interface NullSchema extends BaseJsonSchema {
+    type: 'null';
+}
+interface EnumSchema extends BaseJsonSchema {
+    type: 'enum';
+    values: (string | number | boolean)[];
+}
+interface ArrayItemMeta {
+    optional?: boolean;
+    rest?: boolean;
+    name?: string;
+}
+interface ArraySchema extends BaseJsonSchema {
+    type: 'array';
+    items: JsonSchema | (JsonSchema & ArrayItemMeta)[];
+}
+interface ObjectSchema extends BaseJsonSchema {
+    type: 'object';
+    properties: Record<string, JsonSchema>;
+    required?: string[];
+    indexedProperties?: JsonSchema;
+}
+interface RefSchema extends BaseJsonSchema {
+    type: 'ref';
+    name: string;
+}
+interface AnyOfSchema extends BaseJsonSchema {
+    type: 'complex';
+    anyOf: JsonSchema[];
+}
+interface AllOfSchema extends BaseJsonSchema {
+    type: 'complex';
+    allOf: JsonSchema[];
+}
+interface NeverSchema extends BaseJsonSchema {
+    type: 'never';
+}
+interface AnySchema extends BaseJsonSchema {
+    type: 'any';
+}
+interface UndefinedSchema extends BaseJsonSchema {
+    type: 'undefined';
+}
+type JsonSchema = StringSchema | NumberSchema | BooleanSchema | NullSchema | EnumSchema | ArraySchema | ObjectSchema | RefSchema | AnyOfSchema | AllOfSchema | NeverSchema | AnySchema | UndefinedSchema;
+type SchemaBuilderEntry = {
+    name: string;
+} | {
+    name: string;
+    model: string;
+} | {
+    name: string;
+    inline: string;
+} | {
+    name: string;
+    type: Type;
+    node?: Node;
+};
+type TypesSchema = {
+    schema: Record<string, JsonSchema>;
+    refs: Record<string, JsonSchema>;
+    mappedReferences: Record<string, string>;
+};
+type DomainTypesSchema = Omit<TypesSchema, 'mappedReferences'>;
+type NamedTsTypeEntry = Extract<SchemaBuilderEntry, {
+    type: Type;
+}>;
+type NamedInlineTypeEntry = Extract<SchemaBuilderEntry, {
+    inline: string;
+}>;
+type NamedModelTypeEntry = Extract<SchemaBuilderEntry, {
+    model: string;
+}>;
+type EndpointData = {
+    path: string;
+    method: string;
+    domains: string[];
+    disabledDomains: string[];
+    query?: string;
+    request?: string;
+    responses?: Record<number, string>;
+};
+
+interface PipelineOptions {
+    useExistingBuild?: boolean;
+    watch?: boolean;
+}
+
+type CountDuplicates<K extends string, Seen extends string[], Count extends number[] = []> = Seen extends [infer First extends string, ...infer Rest extends string[]] ? First extends K ? CountDuplicates<K, Rest, [...Count, any]> : CountDuplicates<K, Rest, Count> : Count;
+type NormalizeParam<Param extends string, Seen extends string[]> = CountDuplicates<Param, Seen>['length'] extends 0 ? Param : `${NormalizeParam<`${Param}_${CountDuplicates<Param, Seen>['length']}`, Seen>}`;
+type NormalizePath<T extends string, Seen extends string[] = [], Output extends string = ''> = T extends `${infer Before}:${infer Param}/${infer Rest}` ? NormalizePath<`/${Rest}`, [
+    ...Seen,
+    Param
+], `${Output}${Before}:${NormalizeParam<Param, Seen>}`> : T extends `${infer Before}:${infer Param}` ? `${Output}${Before}:${NormalizeParam<Param, Seen>}` : `${Output}${T}`;
+
+interface ControllerOptions<T extends string = string> {
+    path: NormalizePath<T>;
+}
+declare const ApinniController: <Path extends string = string>(_options: ControllerOptions<Path>) => <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => T;
+
+type DisabledOptions = {
+    disabled: boolean;
+    reason?: string;
+} | {
+    domains: Partial<{
+        '*': boolean;
+        [domain: string]: boolean;
+    }>;
+    reason?: string;
+};
+declare const ApinniDisabled: (_options?: DisabledOptions) => (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+
+interface DomainOptions {
+    domains: Array<string>;
+}
+declare const ApinniDomain: (_options: DomainOptions) => <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => T;
+
+type OptionDefinition = {
+    model: string;
+    name?: string;
+};
+interface EndpointOptions<T extends string = string> {
+    path: NormalizePath<T>;
+    method: string;
+    query?: OptionDefinition | Array<string>;
+    request?: OptionDefinition;
+    responses?: OptionDefinition | {
+        [status: number]: OptionDefinition;
+    };
+}
+type TypeDefinition$1 = {
+    type: unknown;
+    name?: string;
+};
+type ResponseType = TypeDefinition$1 | {
+    [status: number]: TypeDefinition$1;
+};
+interface TypeShape {
+    query?: TypeDefinition$1;
+    request?: TypeDefinition$1;
+    responses?: ResponseType;
+}
+type EndpointShape<T extends TypeShape = TypeShape> = T;
+type ApinniEndpointDecorator = <Shape extends TypeShape = TypeShape, Path extends string = string>(options: EndpointOptions<Path>) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare const ApinniEndpoint: ApinniEndpointDecorator;
+
+type DecoratorVariant = 'class' | 'method';
+type DecoratorType = 'compile-time' | 'run-time';
+type HandlerEvent = 'register' | 'unregister';
+interface DecoratorDefinition<T extends DecoratorVariant = DecoratorVariant> {
+    name: string;
+    variant: T;
+    type: DecoratorType;
+    handler: (event: HandlerEvent, params: {
+        target: any;
+        decorator: Decorator;
+    } & (T extends 'method' ? {
+        propertyKey: string | symbol;
+    } : Record<never, never>)) => void;
+}
+
+interface ShareableRegistry {
+    register: <T extends DecoratorVariant>(definition: DecoratorDefinition<T>) => void;
+}
+interface ShareableContext<ClassMeta extends Record<string, any> = Record<string, any>, MethodMeta extends Record<string, any> = Record<string, any>> {
+    registerClassMetadata(target: any, metadata: Partial<Omit<ClassMetadata, 'target'> & ClassMeta>): void;
+    registerMethodMetadata(target: any, propertyKey: string | symbol, metadata: Partial<MethodMetadata & MethodMeta>): void;
+}
+
+interface ClassMetadata {
+    target: any;
+    disabledDomains?: Partial<{
+        '*': boolean;
+        [domain: string]: boolean;
+    }>;
+    disabledReason?: string;
+    path?: string;
+    domains?: Array<string>;
+    [key: string]: any;
+}
+interface InternalClassMetadata extends ClassMetadata {
+    decorator: Decorator;
+}
+type TypeDefinition = {
+    name?: string;
+    model: string;
+} | {
+    name?: string;
+    type: Type;
+    node: Node;
+};
+type QueryDefinition = {
+    name?: string;
+    inline: string;
+};
+interface MethodMetadata {
+    path: string;
+    method: string;
+    query?: TypeDefinition | QueryDefinition;
+    request?: TypeDefinition;
+    responses?: Record<number, TypeDefinition>;
+    target: any;
+    propertyKey: string | symbol;
+    descriptor: PropertyDescriptor;
+    disabledDomains?: Partial<{
+        '*': boolean;
+        [domain: string]: boolean;
+    }>;
+    disabledReason?: string;
+    domains?: Array<string>;
+    [key: string]: any;
+}
+interface InternalMethodMetadata extends MethodMetadata {
+    decorator: Decorator;
+}
+interface IGenerationContext extends ShareableContext {
+    getClassMetadata(): ClassMetadata[];
+    getMethodMetadata(): MethodMetadata[];
+    getPreparedData(): MethodMetadata[];
+    filterEnabled(): void;
+}
+
+type ApiSchema = {
+    endpoints: EndpointData[];
+    schema: TypesSchema;
+};
+
+interface SharedContext<T = any> {
+    /** Plugin-specific shared context data */
+    data: T;
+}
+interface DependencyOptions {
+    allowContextManipulation?: boolean;
+}
+interface Dependency {
+    plugin: ShareablePlugin;
+    options?: DependencyOptions;
+}
+interface OverridedContext<T extends Record<string, any> = Record<string, any>, U extends Record<string, any> = Record<string, any>> {
+    classMetadata: T;
+    methodMetadata: U;
+}
+type ExtractDependenciesOverridedContext<Dependencies extends Dependency[] = []> = Dependencies extends [Dependency, ...Dependency[]] ? {
+    [K in keyof Dependencies]: Dependencies[K]['options'] extends DependencyOptions ? Dependencies[K]['options']['allowContextManipulation'] extends true ? ExtractOverridedContext<Dependencies[K]['plugin']> : OverridedContext : OverridedContext;
+}[number] : OverridedContext;
+/**
+ * Base configuration and hooks for a Apinni plugin
+ */
+interface BaseApinniPluginProps<OverridedGlobalContext extends OverridedContext = OverridedContext, Dependencies extends Dependency[] = [], IsShareable extends boolean = false, SharedContextData extends [IsShareable] extends [true] ? any : never = [
+    IsShareable
+] extends [true] ? any : never> {
+    /** Unique identifier for the plugin */
+    name: string;
+    /** Plugin configuration options */
+    config?: {
+        /**
+         * Set to `true` if this plugin should be available as a dependency
+         * for other plugins. Only shareable plugins can be used as dependencies.
+         *
+         * **Note:**
+         *
+         * If plugin is used as dependency - the manipulation with global context
+         * could be restricted. By default the follow methods will be skipped:
+         * 1. `onRegisterMetadata()`
+         * 2. `onGenerateTypes()`
+         *
+         * Only if consumer pass the option **allowContextManipulation** as `true`
+         * all the hooks will be executed.
+         */
+        shareable?: IsShareable;
+    };
+    /**
+     * Plugin lifecycle hooks executed in the following order:
+     * 1. `onInitialize()` - Initialize decorators in registry
+     * 2. `onAfterDecoratorsProcessed()` - Process after all decorators are loaded
+     * 3. `onProvideSharedContext()` - Share context with dependent plugins (shareable only)
+     * 4. `onConsumeDependencyContexts()` - Consume contexts from dependencies (with dependencies only)
+     * 5. `onRegisterMetadata()` - Register metadata in generation context
+     * 6. `onGenerateTypes()` - Generate final types
+     */
+    hooks: {
+        /**
+         * Initialize custom decorators in the registry.
+         * This allows the library to import and process your decorators.
+         *
+         * @param registry - The decorator registry to register custom decorators
+         */
+        onInitialize: (registry: ShareableRegistry, mode: ApinniRunMode) => Promise<void> | void;
+        /**
+         * Called after all decorators have been processed.
+         * Use this hook to prepare and validate your plugin data.
+         */
+        onAfterDecoratorsProcessed?: () => void;
+        /**
+         * Register metadata in the generation context.
+         * This is where you can add plugin-specific metadata for code generation.
+         *
+         * @param context - The generation context to register metadata
+         */
+        onRegisterMetadata?: (context: ShareableContext<OverridedGlobalContext['classMetadata'] & ExtractDependenciesOverridedContext<Dependencies>['classMetadata'], OverridedGlobalContext['methodMetadata'] & ExtractDependenciesOverridedContext<Dependencies>['methodMetadata']>) => void;
+        /**
+         * Generate types and perform final code generation tasks.
+         * This is the final hook in the plugin lifecycle.
+         *
+         * @param context - The generation context for type generation
+         */
+        onGenerateTypes?: (schema: ApiSchema, metadata?: {
+            classMetadata: Array<ClassMetadata & Partial<OverridedGlobalContext['classMetadata'] & ExtractDependenciesOverridedContext<Dependencies>['classMetadata']>>;
+            methodMetadata: Array<MethodMetadata & Partial<OverridedGlobalContext['methodMetadata'] & ExtractDependenciesOverridedContext<Dependencies>['methodMetadata']>>;
+        }) => Promise<void>;
+    } & ([IsShareable] extends [true] ? {
+        /**
+         * Provide shared context data to dependent plugins.
+         * Only called for plugins with `shareable: true`.
+         *
+         * @returns Shared context that will be passed to dependent plugins
+         */
+        onProvideSharedContext: () => SharedContext<SharedContextData>;
+    } : Record<never, never>);
+    /** Array of shareable plugins that this plugin depends on */
+    dependencies?: Dependencies;
+}
+/**
+ * Utility type to extract the shared context type from a shareable plugin
+ */
+type ExtractSharedContext<T extends ShareablePlugin> = T extends ShareablePlugin<infer _, infer __, infer C> ? SharedContext<C> : never;
+/**
+ * Utility type to extract the overrided global context type from a shareable plugin
+ */
+type ExtractOverridedContext<T extends ShareablePlugin> = T extends ShareablePlugin<infer R, infer _, infer __> ? R : never;
+/**
+ * Apinni Plugin definition with conditional dependency context handling
+ */
+type InternalApinniPlugin<OverridedGlobalContext extends OverridedContext = OverridedContext, Dependencies extends Dependency[] = [], IsShareable extends boolean = false, SharedContext extends [IsShareable] extends [true] ? any : never = [
+    IsShareable
+] extends [true] ? any : never> = Dependencies extends [Dependency, ...Dependency[]] ? BaseApinniPluginProps<OverridedGlobalContext, Dependencies, IsShareable, SharedContext> & {
+    /** Required dependencies that must be shareable plugins */
+    dependencies: {
+        [K in keyof Dependencies]: Dependencies[K] & Dependency;
+    };
+    hooks: {
+        /**
+         * Process shared contexts from dependency plugins.
+         * Called after all dependencies have provided their shared contexts.
+         *
+         * @param contexts - Array of shared contexts from dependency plugins
+         */
+        onConsumeDependencyContexts: (contexts: {
+            [K in keyof Dependencies]: ExtractSharedContext<Dependencies[K]['plugin']>;
+        }) => void;
+    };
+} : BaseApinniPluginProps<OverridedGlobalContext, Dependencies, IsShareable, SharedContext>;
+type ApinniPlugin<OverridedGlobalContext extends OverridedContext = OverridedContext, Dependencies extends Dependency[] = [], IsShareable extends boolean = false, SharedContext extends [IsShareable] extends [true] ? any : never = [
+    IsShareable
+] extends [true] ? any : never> = InternalApinniPlugin<OverridedGlobalContext, Dependencies, IsShareable, SharedContext> & {
+    readonly __brand?: 'ApinniPlugin';
+};
+/**
+ * Represents a plugin that can be shared as a dependency
+ */
+type ShareablePlugin<OverridedGlobalContext extends OverridedContext = OverridedContext, Dependencies extends Dependency[] = [], Context = any> = ApinniPlugin<OverridedGlobalContext, Dependencies, true, Context> & {
+    readonly __brand?: 'ApinniPlugin';
+};
+type PluginTypes = ApinniPlugin<any, any, false, never> | ShareablePlugin<any, any, any>;
+
+interface ApinniConfig {
+    includePatterns?: string[];
+    excludePattenrs?: string[];
+    plugins: PluginTypes[];
+    outputPath?: string;
+    generateSchemaFiles?: boolean;
+}
+type ApinniRunMode = 'watch' | 'default';
+
+declare function runApinni(config: ApinniConfig, options: PipelineOptions): Promise<void>;
+
+declare const buildPluginWithContext: <OverridedGlobalContext extends OverridedContext = OverridedContext>() => <Dependencies extends Dependency[] = [], IsShareable extends boolean = false, SharedContext extends [IsShareable] extends [true] ? any : never = [IsShareable] extends [true] ? any : never>(plugin: ApinniPlugin<OverridedGlobalContext, Dependencies, IsShareable, SharedContext>) => ApinniPlugin<OverridedGlobalContext, Dependencies, IsShareable, SharedContext>;
+declare const buildPlugin: <Dependencies extends Dependency[] = [], IsShareable extends boolean = false, SharedContext extends [IsShareable] extends [true] ? any : never = [IsShareable] extends [true] ? any : never>(plugin: ApinniPlugin<OverridedContext, Dependencies, IsShareable, SharedContext>) => ApinniPlugin<OverridedContext, Dependencies, IsShareable, SharedContext>;
+declare function extractDecoratorArgValue<T>(decorator: Decorator): T | null;
+
+export { type AllOfSchema, type AnyOfSchema, type AnySchema, type ApiSchema, type ApinniConfig, ApinniController, ApinniDisabled, ApinniDomain, ApinniEndpoint, type ApinniPlugin, type ApinniRunMode, type ArrayItemMeta, type ArraySchema, type BaseApinniPluginProps, type BooleanSchema, type ClassMetadata, type ControllerOptions, type DecoratorDefinition, type DecoratorType, type DecoratorVariant, type Dependency, type DependencyOptions, type DisabledOptions, type DomainOptions, type DomainTypesSchema, type EndpointData, type EndpointOptions, type EndpointShape, type EnumSchema, type HandlerEvent, type IGenerationContext, type InternalClassMetadata, type InternalMethodMetadata, type JsonSchema, type JsonSchemaType, type MethodMetadata, type NamedInlineTypeEntry, type NamedModelTypeEntry, type NamedTsTypeEntry, type NeverSchema, type NullSchema, type NumberSchema, type ObjectSchema, type OverridedContext, type PipelineOptions, type PluginTypes, type RefSchema, type SchemaBuilderEntry, type SchemaDefinitionProperties, type ShareableContext, type ShareablePlugin, type ShareableRegistry, type SharedContext, type StringSchema, type TypesSchema, type UndefinedSchema, buildPlugin, buildPluginWithContext, extractDecoratorArgValue, runApinni };