@stacksjs/dtsx/dist/src/branded-types.d.ts

A modern, fast .d.ts generation tool, powered by Bun.

/**
 * Type guard and constructor for FilePath
 */
export declare function asFilePath(path: string): FilePath;
/**
 * Type guard and constructor for DirectoryPath
 */
export declare function asDirectoryPath(path: string): DirectoryPath;
/**
 * Type guard and constructor for GlobPattern
 */
export declare function asGlobPattern(pattern: string): GlobPattern;
/**
 * Type guard and constructor for SourceCode
 */
export declare function asSourceCode(code: string): SourceCode;
/**
 * Type guard and constructor for DtsContent
 */
export declare function asDtsContent(content: string): DtsContent;
/**
 * Type guard and constructor for ModuleSpecifier
 */
export declare function asModuleSpecifier(specifier: string): ModuleSpecifier;
/**
 * Type guard and constructor for TypeName
 */
export declare function asTypeName(name: string): TypeName;
/**
 * Type guard and constructor for DeclarationName
 */
export declare function asDeclarationName(name: string): DeclarationName;
/**
 * Type guard and constructor for AbsolutePath
 */
export declare function asAbsolutePath(path: string): AbsolutePath;
/**
 * Type guard and constructor for RelativePath
 */
export declare function asRelativePath(path: string): RelativePath;
/**
 * Type guard and constructor for JsonString
 */
export declare function asJsonString(json: string): JsonString;
/**
 * Check if a value is a branded type of a specific brand
 */
export declare function isBranded<T, B extends string>(value: unknown, _brand: B): value is Brand<T, B>;
/**
 * Unwrap a branded type to its base type
 * Useful when you need to pass branded types to external APIs
 */
export declare function unwrap<T>(branded: Brand<T, string>): T;
/**
 * Safe path operations that preserve branding.
 * Uses ESM imports hoisted to module scope so each call avoids the per-call
 * `require('node:path')` overhead that the previous CommonJS-style implementation
 * incurred.
 * @defaultValue
 * ```ts
 * {
 *   join: (base: DirectoryPath, ...segments: string[]) => FilePath,
 *   dirname: (path: FilePath) => DirectoryPath,
 *   basename: (path: FilePath) => string,
 *   resolve: (...segments: string[]) => AbsolutePath,
 *   isAbsolute: (path: string) => path is AbsolutePath,
 *   relative: (from: DirectoryPath, to: FilePath) => RelativePath
 * }
 * ```
 */
export declare const BrandedPath: {
  /**
   * Join path segments, returning appropriate branded type
   */
  join: (base: DirectoryPath, ...segments: string[]) => FilePath;
  /**
   * Get directory name from a file path
   */
  dirname: (path: FilePath) => DirectoryPath;
  /**
   * Get base name from a file path
   */
  basename: (path: FilePath) => string;
  /**
   * Resolve path to absolute
   */
  resolve: (...segments: string[]) => AbsolutePath;
  /**
   * Check if path is absolute
   */
  isAbsolute: (path: string) => path is AbsolutePath;
  /**
   * Get relative path from one path to another
   */
  relative: (from: DirectoryPath, to: FilePath) => RelativePath
};
/**
 * Generic branded type creator
 */
export type Brand<T, B extends string> = T & { readonly [__brand]: B }
/**
 * Branded type for file paths
 * Ensures file paths are validated before use
 */
export type FilePath = Brand<string, 'FilePath'>;
/**
 * Branded type for directory paths
 */
export type DirectoryPath = Brand<string, 'DirectoryPath'>;
/**
 * Branded type for glob patterns
 */
export type GlobPattern = Brand<string, 'GlobPattern'>;
/**
 * Branded type for TypeScript source code
 */
export type SourceCode = Brand<string, 'SourceCode'>;
/**
 * Branded type for declaration file content
 */
export type DtsContent = Brand<string, 'DtsContent'>;
/**
 * Branded type for module specifiers (import paths)
 */
export type ModuleSpecifier = Brand<string, 'ModuleSpecifier'>;
/**
 * Branded type for type names
 */
export type TypeName = Brand<string, 'TypeName'>;
/**
 * Branded type for declaration names
 */
export type DeclarationName = Brand<string, 'DeclarationName'>;
/**
 * Branded type for validated JSON strings
 */
export type JsonString = Brand<string, 'JsonString'>;
/**
 * Branded type for absolute paths
 */
export type AbsolutePath = Brand<string, 'AbsolutePath'>;
/**
 * Branded type for relative paths
 */
export type RelativePath = Brand<string, 'RelativePath'>;
/**
 * Type utility to extract the brand from a branded type
 */
export type ExtractBrand<T> = T extends Brand<unknown, infer B> ? B : never;
/**
 * Type utility to extract the base type from a branded type
 */
export type ExtractBase<T> = T extends Brand<infer U, string> ? U : T;