UNPKG

jsrepo

Version:

A CLI to add shared code from remote repositories.

853 lines (840 loc) 26.8 kB
import * as v from 'valibot'; declare const MANIFEST_FILE = "jsrepo-manifest.json"; declare const CONFIG_FILE = "jsrepo.json"; declare const blockSchema: v.ObjectSchema<{ readonly name: v.StringSchema<undefined>; readonly category: v.StringSchema<undefined>; readonly localDependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly dependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly devDependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly tests: v.BooleanSchema<undefined>; readonly docs: v.OptionalSchema<v.BooleanSchema<undefined>, false>; readonly list: v.OptionalSchema<v.BooleanSchema<undefined>, true>; /** Where to find the block relative to root */ readonly directory: v.StringSchema<undefined>; readonly subdirectory: v.BooleanSchema<undefined>; readonly files: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly _imports_: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>; }, undefined>; declare const categorySchema: v.ObjectSchema<{ readonly name: v.StringSchema<undefined>; readonly blocks: v.ArraySchema<v.ObjectSchema<{ readonly name: v.StringSchema<undefined>; readonly category: v.StringSchema<undefined>; readonly localDependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly dependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly devDependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly tests: v.BooleanSchema<undefined>; readonly docs: v.OptionalSchema<v.BooleanSchema<undefined>, false>; readonly list: v.OptionalSchema<v.BooleanSchema<undefined>, true>; /** Where to find the block relative to root */ readonly directory: v.StringSchema<undefined>; readonly subdirectory: v.BooleanSchema<undefined>; readonly files: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly _imports_: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>; }, undefined>, undefined>; }, undefined>; declare const manifestMeta: v.ObjectSchema<{ readonly authors: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; readonly bugs: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly homepage: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly repository: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly tags: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; }, undefined>; declare const peerDependencySchema: v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{ readonly version: v.StringSchema<undefined>; readonly message: v.StringSchema<undefined>; }, undefined>], undefined>, undefined>; type PeerDependency = v.InferOutput<typeof peerDependencySchema>; declare const configFileSchema: v.ObjectSchema<{ readonly name: v.StringSchema<undefined>; readonly path: v.StringSchema<undefined>; readonly expectedPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly optional: v.OptionalSchema<v.BooleanSchema<undefined>, false>; }, undefined>; type ConfigFile = v.InferOutput<typeof configFileSchema>; declare const manifestConfigFileSchema: v.ObjectSchema<{ readonly dependencies: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; readonly devDependencies: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; readonly name: v.StringSchema<undefined>; readonly path: v.StringSchema<undefined>; readonly expectedPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly optional: v.OptionalSchema<v.BooleanSchema<undefined>, false>; }, undefined>; declare const accessLevel: v.UnionSchema<[v.LiteralSchema<"public", undefined>, v.LiteralSchema<"private", undefined>, v.LiteralSchema<"marketplace", undefined>], undefined>; declare const manifestSchema: v.ObjectSchema<{ readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly version: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly meta: v.OptionalSchema<v.ObjectSchema<{ readonly authors: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; readonly bugs: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly homepage: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly repository: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly tags: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; }, undefined>, undefined>; readonly access: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<"public", undefined>, v.LiteralSchema<"private", undefined>, v.LiteralSchema<"marketplace", undefined>], undefined>, undefined>; readonly defaultPaths: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; readonly peerDependencies: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{ readonly version: v.StringSchema<undefined>; readonly message: v.StringSchema<undefined>; }, undefined>], undefined>, undefined>, undefined>; readonly configFiles: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{ readonly dependencies: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; readonly devDependencies: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; readonly name: v.StringSchema<undefined>; readonly path: v.StringSchema<undefined>; readonly expectedPath: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly optional: v.OptionalSchema<v.BooleanSchema<undefined>, false>; }, undefined>, undefined>, undefined>; readonly categories: v.ArraySchema<v.ObjectSchema<{ readonly name: v.StringSchema<undefined>; readonly blocks: v.ArraySchema<v.ObjectSchema<{ readonly name: v.StringSchema<undefined>; readonly category: v.StringSchema<undefined>; readonly localDependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly dependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly devDependencies: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly tests: v.BooleanSchema<undefined>; readonly docs: v.OptionalSchema<v.BooleanSchema<undefined>, false>; readonly list: v.OptionalSchema<v.BooleanSchema<undefined>, true>; /** Where to find the block relative to root */ readonly directory: v.StringSchema<undefined>; readonly subdirectory: v.BooleanSchema<undefined>; readonly files: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly _imports_: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>; }, undefined>, undefined>; }, undefined>, undefined>; }, undefined>; type Meta = v.InferOutput<typeof manifestMeta>; type Category = v.InferOutput<typeof categorySchema>; type Block = v.InferOutput<typeof blockSchema>; type Manifest = v.InferOutput<typeof manifestSchema>; /** This is just a helper type used only within this file */ type _Result<T, E> = { ok: true; val: T; } | { ok: false; err: E; }; /** Result allows you to show to a consumer that a function might throw and force them to handle it. * * `T` Value type * * `E` Error type * * ## Usage * * ```ts * function functionThatMightFail(): Result<T, E>; * ``` * * ## Usage * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello, World!"); * * const result = functionThatMightFail(); * * console.log(result.unwrap()); // "Hello, World!" * ``` */ declare class Result<T, E> { private readonly _result; constructor(result: _Result<T, E>); /** Allows you to run callbacks based on the result. * * @param success callback to be run when result is success * @param failure callback to be run when result is failure * @returns * * ## Usage * * ```ts * result.match( * (val) => val, * () => { * throw new Error('oops!') * } * ); * ``` * * ## Usage * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello, World!"); * * const result = functionThatMightFail(); * * const val = result.match( * (val) => val, * () => { * throw new Error('oops!') * } * ); * * console.log(val); // "Hello, World!" * ``` */ match<A, B = A>(success: (val: T) => A, failure: (err: E) => B): A | B; /** Maps `Result<T, E>` to `Result<A, E>` using the passed mapping function * * @param fn Mapping function * @returns * * ## Usage * * ```ts * result.map((val) => val.length); * ``` * * ## Usage * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello, World!"); * * const result = functionThatMightFail(); * * const hello = result.map((val) => val.slice(0, 5)); * * console.log(hello.unwrap()); // "Hello" * ``` */ map<A>(fn: (val: T) => A): Result<A, E>; /** In the `Ok` case returns the mapped value using the function else returns `defaultVal` * * @param defaultVal Value to be returned when `Err` * @param fn Mapping function to map in case of `Ok` * @returns * * ## Usage * * ```ts * result.mapOr(1, (val) => val.length); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("foo"); * * const result = functionThatMightFail(); * * const length = result.mapOr(1, (val) => val.length); * * console.log(length); // 3 * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * const length = result.mapOr(1, (val) => val.length); * * console.log(length); // 1 * ``` */ mapOr<A>(defaultVal: A, fn: (val: T) => A): A; /** In the `Ok` case returns the mapped value using `fn` else returns value of `def` * * @param def Mapping function called when `Err` * @param fn Mapping function called when `Ok` * @returns * * ## Usage * * ```ts * result.mapOrElse(() => 1, (val) => val.length); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("foo"); * * const result = functionThatMightFail(); * * const length = result.mapOrElse(() => 1, (val) => val.length); * * console.log(length); // 3 * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * const length = result.mapOr(() => 1, (val) => val.length); * * console.log(length); // 1 * ``` */ mapOrElse<A>(def: (err: E) => A, fn: (val: T) => A): A; /** Maps `Result<T, E>` to `Result<T, A>` using the passed mapping function * * @param fn Mapping function * @returns * * ## Usage * * ```ts * result.mapErr((err) => getCodeMsg(err)); * ``` * * ## Usage * * ```ts * const functionThatMightFail = (): Result<string, string> => Err(10); * * const result = functionThatMightFail(); * * const message = result.mapErr(() => "Error"); * * console.log(message); // "Error" * ``` */ mapErr<A>(fn: (err: E) => A): Result<T, A>; /** In the `Err` case returns the mapped value using the function else returns `defaultVal` * * @param defaultVal Value to be returned when `Ok` * @param fn Mapping function to map in case of `Err` * @returns * * ## Usage * * ```ts * result.mapErrOr("Should've been error", (err) => getCodeMsg(err)); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("foo"); * * const result = functionThatMightFail(); * * const message = result.mapErrOr("Should've been error", () => "Error"); * * console.log(message); // "Should've been error" * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err(10); * * const result = functionThatMightFail(); * * const message = result.mapErrOr("Should've been error", () => "Error"); * * console.log(message); // "Error" * ``` */ mapErrOr<A>(defaultVal: A, fn: (err: E) => A): A; /** In the `Err` case returns the mapped value using the function else returns value of `def` * * @param def Mapping function called when `Ok` * @param fn Mapping function called when `Err` * @returns * * ## Usage * * ```ts * result.mapErrOrElse(() => "Value", (_) => "Error!"); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("foo"); * * const result = functionThatMightFail(); * * const length = result.mapErrOrElse(() => 1, (val) => val.length); * * console.log(length); // 1 * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * const length = result.mapOr(() => 1, (val) => val.length); * * console.log(length); // 4 * ``` */ mapErrOrElse<A>(def: (val: T) => A, fn: (err: E) => A): A; /** Returns true if result is `Ok` * * @returns * * ## Usage * * ```ts * result.isOk(); * ``` */ isOk(): boolean; /** Returns true if result is `Err` * * @returns * * ## Usage * * ```ts * result.isErr(); * ``` */ isErr(): boolean; /** Tries to return value if value is `Err` throws generic error message. * * @returns * * ## Usage * * ```ts * result.unwrap(); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * console.log(result.unwrap()); // "Hello!" * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * result.unwrap(); // Error: Attempted to call `.unwrap()` on a non `Ok` value. * ``` */ unwrap(): T; /** Tries to return err if value is `Ok` throws generic error message. * * @returns * * ## Usage * * ```ts * result.unwrapErr(); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * result.unwrapErr(); // Error: Attempted to call `.unwrapErr()` on a non `Err` value. * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapErr()); // "oops!" * ``` */ unwrapErr(): E; /** Tries to unwrap the value if value is `Err` returns `defaultVal` * * @param defaultVal Value to be returned if `Err` * @returns * * ## Usage * * ```ts * result.unwrapOr(7); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapOr("Yellow!")); // "Hello!" * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapOr("Yellow!")); // "Yellow!" * ``` */ unwrapOr(defaultVal: T): T; /** Tries to unwrap the error if vale is `Ok` returns `defaultVal` * * @param defaultVal * @returns * * ## Usage * * ```ts * result.unwrapErrOr("Error"); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapErrOr("Yellow!")); // "Yellow!" * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapErrOr("Yellow!")); // "oops!" * ``` */ unwrapErrOr(defaultVal: E): E; /** Tries to return the value if value is `Err` calls `fn` * * @param fn Function called if `Err` * * ## Usage * * ```ts * result.unwrapOrElse(() => "Hello!"); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapOrElse(() => "oops!")); // "Hello!" * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapOrElse(() => "Hello!")); // "Hello!" * ``` * */ unwrapOrElse(fn: (err: E) => T): T; /** Tries to return the error if value is `Ok` calls `fn` * * @param fn Function called if `Ok` * * ## Usage * * ```ts * result.unwrapErrOrElse(() => "Error!"); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapErrOrElse(() => "oops!")); // "oops!" * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * console.log(result.unwrapErrOrElse(() => "Hello!")); // "oops!" * ``` * */ unwrapErrOrElse(fn: (val: T) => E): E; /** Tries to return value if value is `Err` throws custom error message. * * @param message Message to show when value is `Err` * @returns * * ## Usage * * ```ts * result.expect("Custom message"); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * console.log(result.expect("I failed!")); // "Hello!" * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * result.expect("I failed!"); // Error: I failed! * ``` */ expect(message: string): T; /** Tries to return error value if value is `Ok` throws custom error message * * @param message * @returns * * ## Usage * * ```ts * result.expectErr("Custom message"); * ``` * * ## Usage * * ### When `Ok` * * ```ts * const functionThatMightFail = (): Result<string, string> => Ok("Hello!"); * * const result = functionThatMightFail(); * * console.log(result.expectErr("I failed!")); // Error: I failed! * ``` * * ### When `Err` * * ```ts * const functionThatMightFail = (): Result<string, string> => Err("oops!"); * * const result = functionThatMightFail(); * * console.log(result.expectErr("I failed!")); // "oops!" * ``` */ expectErr(message: string): E; } interface RegistryProvider { /** Short name for the provider that will be used when it is displayed to the user */ name: string; /** Used to determine if the provided url belongs to this provider * * @param url * @returns */ matches: (url: string) => boolean; /** Parse a URL that belongs to the provider * * @param url * @param opts * @returns */ parse: (url: string, opts: ParseOptions) => ParseResult; /** Parses the url and returns the origin of the url. * * `github/ieedan/std/tree/next -> github/ieedan/std` * * `https://example.com/new-york -> https://example.com` * * @param url * @returns */ baseUrl: (url: string) => string; /** Gets the provider state by parsing the url and taking care of any loose ends * * @param url * @returns */ state: (url: string, opts?: StateOptions) => Promise<RegistryProviderState>; /** Returns a URL to the raw path of the resource provided in the resourcePath * * @param repoPath * @param resourcePath * @returns */ resolveRaw: (state: RegistryProviderState, resourcePath: string) => Promise<URL>; /** Different providers use different authorization schemes. * Provide this method with a token to get the key value pair for the authorization header. * * @param token * @returns */ authHeader?: (token: string) => [string, string]; /** Returns a formatted error for a fetch error giving possible reasons for failure */ formatFetchError: (state: RegistryProviderState, filePath: string, error: unknown) => string; } type ParseOptions = { /** Set true when the provided path ends with `<category>/<block>` */ fullyQualified?: boolean; }; type ParseResult = { /** a universal url ex: `https://github.com/ieedan/std -> github/ieedan/std` */ url: string; /** The block specifier `<category>/<block>` */ specifier?: string; }; type StateOptions = { token?: string; /** Override the fetch method. */ fetch?: typeof fetch; }; /** Pass this to the `.provider` property of this to access the methods for this provider */ interface RegistryProviderState { url: string; provider: RegistryProvider; } interface AzureProviderState extends RegistryProviderState { owner: string; repoName: string; project: string; refs: 'heads' | 'tags'; ref: string; } /** Valid paths * * `azure/<org>/<project>/<repo>/(tags|heads)/<ref>` */ declare const azure: RegistryProvider; interface BitBucketProviderState extends RegistryProviderState { owner: string; repoName: string; ref: string; } /** Valid paths * * `bitbucket/ieedan/std` * * `https://bitbucket.org/ieedan/std/src/main/` * * `https://bitbucket.org/ieedan/std/src/next/` * * `https://bitbucket.org/ieedan/std/src/v2.0.0/` * */ declare const bitbucket: RegistryProvider; interface GitHubProviderState extends RegistryProviderState { owner: string; repoName: string; ref: string; } /** Valid paths * * `https://github.com/<owner>/<repo>` * * `github/<owner>/<repo>` * * `github/<owner>/<repo>/tree/<ref>` */ declare const github: RegistryProvider; interface GitLabProviderState extends RegistryProviderState { baseUrl: string; owner: string; repoName: string; ref: string; } /** Valid paths * * `https://gitlab.com/ieedan/std` * * `https://gitlab.com/ieedan/std/-/tree/next` * * `https://gitlab.com/ieedan/std/-/tree/v2.0.0` * * `https://gitlab.com/ieedan/std/-/tree/v2.0.0?ref_type=tags` * * Self hosted: * * `gitlab:https://example.com/ieedan/std` */ declare const gitlab: RegistryProvider; /** Valid paths * * `(https|http)://example.com` */ declare const http: RegistryProvider; interface JsrepoProviderState extends RegistryProviderState { scope: string; registryName: string; version: string; } /** Valid paths * * `@ieedan/std` * `@ieedan/std@latest` * `@ieedan/std@1.0.0` * `@ieedan/std@1.0.0/ts/math` */ declare const jsrepo: RegistryProvider; declare const providers: RegistryProvider[]; declare function selectProvider(url: string): RegistryProvider | undefined; type FetchOptions = { token: string; /** Override the fetch method. */ fetch?: typeof fetch; verbose: (str: string) => void; }; declare function fetchRaw(state: RegistryProviderState, resourcePath: string, { verbose, fetch: f, token }?: Partial<FetchOptions>): Promise<Result<string, string>>; declare function fetchManifest(state: RegistryProviderState, { fetch: f, ...rest }?: Partial<FetchOptions>): Promise<Result<Manifest, string>>; export { type AzureProviderState, type BitBucketProviderState, type Block, CONFIG_FILE, type Category, type ConfigFile, type FetchOptions, type GitHubProviderState, type GitLabProviderState, type JsrepoProviderState, MANIFEST_FILE, type Manifest, type Meta, type ParseOptions, type ParseResult, type PeerDependency, type RegistryProvider, type RegistryProviderState, type StateOptions, accessLevel, azure, bitbucket, blockSchema, categorySchema, configFileSchema, fetchManifest, fetchRaw, github, gitlab, http, jsrepo, manifestConfigFileSchema, manifestMeta, manifestSchema, peerDependencySchema, providers, selectProvider };