diff --git a/packages/debug/index.d.ts b/packages/debug/index.d.ts new file mode 100644 index 000000000..c3ec00bd1 --- /dev/null +++ b/packages/debug/index.d.ts @@ -0,0 +1,3 @@ +import initDebug = require('./lib/debug'); + +export = initDebug; diff --git a/packages/debug/lib/debug.d.ts b/packages/debug/lib/debug.d.ts new file mode 100644 index 000000000..f2bee3de1 --- /dev/null +++ b/packages/debug/lib/debug.d.ts @@ -0,0 +1,58 @@ +/** + * A debug logger function, as returned by the `debug` package. + */ +interface Debugger { + (formatter: unknown, ...args: unknown[]): void; + enabled: boolean; + namespace: string; + /** + * The selected colour for this namespace. A string in the browser build, + * a numeric ANSI code under Node (as returned by `selectColor()`). + */ + color: string | number; + log: (...args: unknown[]) => void; + destroy(): boolean; + extend(namespace: string, delimiter?: string): Debugger; +} + +/** + * A map of custom `%`-formatters registered on the `debug` module. + */ +interface Formatters { + [formatter: string]: (value: unknown) => string; +} + +/** + * The underlying `debug` module. + */ +interface DebugModule { + (namespace: string): Debugger; + enable(namespaces: string): void; + disable(): string; + enabled(namespace: string): boolean; + /** Custom formatters, keyed by the format letter (e.g. `debug.formatters.h`). */ + formatters: Formatters; + names: RegExp[]; + skips: RegExp[]; +} + +/** + * Create a debug instance based on your package.json alias/name. + * + * The challenge here is to figure out where your package.json exists. + */ +interface InitDebug { + /** + * @param name - Name of the debug unit. + */ + (name: string): Debugger; + + /** + * The underlying `debug` module. + */ + _base: DebugModule; +} + +declare const initDebug: InitDebug; + +export = initDebug; diff --git a/packages/debug/package.json b/packages/debug/package.json index 921871393..a9e238814 100644 --- a/packages/debug/package.json +++ b/packages/debug/package.json @@ -10,9 +10,11 @@ }, "files": [ "index.js", + "index.d.ts", "lib" ], "main": "index.js", + "types": "index.d.ts", "publishConfig": { "access": "public" }, diff --git a/packages/logging/index.d.ts b/packages/logging/index.d.ts new file mode 100644 index 000000000..ac24e058d --- /dev/null +++ b/packages/logging/index.d.ts @@ -0,0 +1,3 @@ +import logging = require('./lib/logging'); + +export = logging; diff --git a/packages/logging/lib/GhostLogger.d.ts b/packages/logging/lib/GhostLogger.d.ts new file mode 100644 index 000000000..d820406c9 --- /dev/null +++ b/packages/logging/lib/GhostLogger.d.ts @@ -0,0 +1,140 @@ +type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'; + +type Transport = 'stdout' | 'stderr' | 'parent' | 'file' | 'gelf' | 'http' | 'elasticsearch'; + +interface RotationOptions { + enabled?: boolean; + period?: string; + count?: number; + /** + * Use the `@tryghost/bunyan-rotating-filestream` library instead of the + * built-in bunyan rotation. + */ + useLibrary?: boolean; + threshold?: string | number; + gzip?: boolean; + rotateExisting?: boolean; +} + +interface ElasticsearchOptions { + host?: string; + username?: string; + password?: string; + index?: string; + pipeline?: string; + level?: LogLevel; +} + +interface GelfOptions { + host?: string; + port?: number; + options?: object; +} + +interface HttpOptions { + url?: string; + headers?: Record; + username?: string; + password?: string; + level?: LogLevel; +} + +interface GhostLoggerOptions { + /** Name of the logger. Appears in raw log files as `{"name": ...}`. */ + name?: string; + /** Used for creating the file name. */ + domain?: string; + /** Used for creating the file name. */ + env?: string; + /** Used to print short or long log. */ + mode?: string; + /** The default level of all transports except stderr. */ + level?: LogLevel; + /** Whether the body of a request should be logged to the target stream. */ + logBody?: boolean; + /** Transports to log to (e.g. `stdout`, `stderr`, `gelf`, `file`). */ + transports?: Transport[]; + /** File rotation configuration. */ + rotation?: RotationOptions; + /** Path where log files are stored. */ + path?: string; + /** + * Optional filename template for log files. Supports `{env}` and `{domain}` + * placeholders. Defaults to `{domain}_{env}`. + */ + filename?: string; + /** Elasticsearch transport configuration. */ + elasticsearch?: ElasticsearchOptions; + /** Gelf transport configuration. */ + gelf?: GelfOptions; + /** HTTP transport configuration. */ + http?: HttpOptions; + /** Use local time instead of UTC. */ + useLocalTime?: boolean; + /** Optional set of metadata to attach to each log line. */ + metadata?: Record; +} + +/** + * Ghost's logger class. + * + * The logger handles any stdout/stderr logs and streams them into the + * configured transports. + */ +declare class GhostLogger { + name: string; + env: string; + domain: string; + transports: Transport[]; + level: LogLevel; + logBody: boolean; + mode: string; + path: string; + filename: string; + elasticsearch: ElasticsearchOptions; + gelf: GelfOptions; + http: HttpOptions; + useLocalTime: boolean; + metadata: Record; + rotation: RotationOptions; + streams: Record; + serializers: Record unknown>; + + constructor(options?: GhostLoggerOptions); + + /** Sanitize a domain for use in filenames. */ + sanitizeDomain(domain: string): string; + + /** Replace `{env}`/`{domain}` placeholders in a filename template. */ + replaceFilenamePlaceholders(template: string): string; + + /** Remove sensitive data (passwords, keys, cookies, ...) from an object. */ + removeSensitiveData(obj: T): T; + + /** Centralised log function. */ + log(type: LogLevel, args: unknown[]): void; + + trace(...args: unknown[]): void; + debug(...args: unknown[]): void; + info(...args: unknown[]): void; + warn(...args: unknown[]): void; + error(...args: unknown[]): void; + fatal(...args: unknown[]): void; + + /** Create a child logger with some properties bound to every log message. */ + child(boundProperties: Record): GhostLogger; +} + +declare namespace GhostLogger { + export { + LogLevel, + Transport, + RotationOptions, + ElasticsearchOptions, + GelfOptions, + HttpOptions, + GhostLoggerOptions, + }; +} + +export = GhostLogger; diff --git a/packages/logging/lib/logging.d.ts b/packages/logging/lib/logging.d.ts new file mode 100644 index 000000000..604066539 --- /dev/null +++ b/packages/logging/lib/logging.d.ts @@ -0,0 +1,21 @@ +import GhostLogger = require('./GhostLogger'); + +/** + * A pre-configured `GhostLogger` instance (built from `loggingrc` if present), + * with the `GhostLogger` class attached for creating additional instances. + */ +declare const logging: GhostLogger & { + GhostLogger: typeof GhostLogger; +}; + +declare namespace logging { + export type LogLevel = GhostLogger.LogLevel; + export type Transport = GhostLogger.Transport; + export type RotationOptions = GhostLogger.RotationOptions; + export type ElasticsearchOptions = GhostLogger.ElasticsearchOptions; + export type GelfOptions = GhostLogger.GelfOptions; + export type HttpOptions = GhostLogger.HttpOptions; + export type GhostLoggerOptions = GhostLogger.GhostLoggerOptions; +} + +export = logging; diff --git a/packages/logging/package.json b/packages/logging/package.json index 9d9c2f212..259cfd4ce 100644 --- a/packages/logging/package.json +++ b/packages/logging/package.json @@ -10,9 +10,11 @@ }, "files": [ "index.js", + "index.d.ts", "lib" ], "main": "index.js", + "types": "index.d.ts", "publishConfig": { "access": "public" }, diff --git a/packages/pretty-stream/index.d.ts b/packages/pretty-stream/index.d.ts new file mode 100644 index 000000000..9fa5d8e1e --- /dev/null +++ b/packages/pretty-stream/index.d.ts @@ -0,0 +1,3 @@ +import PrettyStream = require('./lib/PrettyStream'); + +export = PrettyStream; diff --git a/packages/pretty-stream/lib/PrettyStream.d.ts b/packages/pretty-stream/lib/PrettyStream.d.ts new file mode 100644 index 000000000..9b58bd322 --- /dev/null +++ b/packages/pretty-stream/lib/PrettyStream.d.ts @@ -0,0 +1,22 @@ +import { Transform, TransformOptions } from 'stream'; + +interface PrettyStreamOptions extends TransformOptions { + /** + * Controls how much detail is printed. Use `'long'` to include the + * pretty-printed request/error body, anything else prints the short form. + * @default 'short' + */ + mode?: string; +} + +/** + * A Bunyan-compatible transform stream that turns raw JSON log records into + * human-readable, colourised output. + */ +declare class PrettyStream extends Transform { + mode: string; + + constructor(options?: PrettyStreamOptions); +} + +export = PrettyStream; diff --git a/packages/pretty-stream/package.json b/packages/pretty-stream/package.json index 0e9bdc90d..d37d62091 100644 --- a/packages/pretty-stream/package.json +++ b/packages/pretty-stream/package.json @@ -10,9 +10,11 @@ }, "files": [ "index.js", + "index.d.ts", "lib" ], "main": "index.js", + "types": "index.d.ts", "publishConfig": { "access": "public" },