docs: more jsdocs on core package

Author: joelgallant

app-config-core/src/config-source.ts

@@ -7,6 +7,9 @@ import { logger } from '@app-config/logging';
 import { ParsedValue, ParsingContext, ParsingExtension } from './parsed-value';
 import { AppConfigError, NotFoundError, ParsingError, BadFileType } from './errors';
 
+/**
+ * File formats that app-config supports.
+ */
 export enum FileType {
   YAML = 'YAML',
   TOML = 'TOML',
@@ -160,6 +163,9 @@ export class FallbackSource extends ConfigSource {
   }
 }
 
+/**
+ * Converts a JSON object to a string, using specified file type.
+ */
 export function stringify(config: Json, fileType: FileType, minimal: boolean = false): string {
   switch (fileType) {
     case FileType.JSON:
@@ -182,6 +188,9 @@ export function stringify(config: Json, fileType: FileType, minimal: boolean = f
   }
 }
 
+/**
+ * Returns which file type to use, based on the file extension.
+ */
 export function filePathAssumedType(filePath: string): FileType {
   switch (extname(filePath).toLowerCase().slice(1)) {
     case 'yml':
@@ -200,6 +209,9 @@ export function filePathAssumedType(filePath: string): FileType {
   }
 }
 
+/**
+ * Parses string based on a file format.
+ */
 export async function parseRawString(contents: string, fileType: FileType): Promise<Json> {
   switch (fileType) {
     case FileType.JSON:
@@ -215,6 +227,9 @@ export async function parseRawString(contents: string, fileType: FileType): Prom
   }
 }
 
+/**
+ * Try to parse string as different file formats, returning the first that worked.
+ */
 export async function guessFileType(contents: string): Promise<FileType> {
   for (const tryType of [FileType.JSON, FileType.TOML, FileType.JSON5, FileType.YAML]) {
     try {

app-config-core/src/parsed-value.ts

@@ -12,15 +12,27 @@ export const InArray = Symbol('InArray');
 /** The property being visited is the root object */
 export const Root = Symbol('Root');
 
+/** Descriptor for what "key" that a value was defined under within JSON */
 export type ParsingExtensionKey =
   | [typeof InObject, string]
   | [typeof InArray, number]
   | [typeof Root];
 
+/**
+ * Arbitrary context that's passed through the hierachy during parsing, only downwards.
+ *
+ * This is used for environment overrides and other options, so that parsing below some
+ * level in an object tree can override what the current environment is.
+ */
 export interface ParsingContext {
   [k: string]: string | string[] | undefined | ParsingContext;
 }
 
+/**
+ * Performs transformations on raw values that were read.
+ *
+ * See https://app-config.dev/guide/intro/extensions.html
+ */
 export interface ParsingExtension {
   (
     value: Json,
@@ -37,6 +49,9 @@ export interface ParsingExtension {
   extensionName?: string;
 }
 
+/**
+ * Callback that will process and potentially transform a value.
+ */
 export type ParsingExtensionTransform = (
   parse: (
     value: Json,
@@ -51,6 +66,7 @@ export type ParsingExtensionTransform = (
   root: Json,
 ) => Promise<ParsedValue> | ParsedValue;
 
+/** Values associated with a ParsedValue */
 export interface ParsedValueMetadata {
   [key: string]: any;
 }
@@ -195,7 +211,7 @@ export class ParsedValue {
     return this;
   }
 
-  /** Lookup property by nested key */
+  /** Lookup property by nested key name(s) */
   property([key, ...rest]: string[]): ParsedValue | undefined {
     if (key === '') return this.property(rest);
 
@@ -350,6 +366,7 @@ function literalParsedValue(raw: Json, source: ConfigSource): ParsedValue {
   return new ParsedValue(source, raw, transformed);
 }
 
+/** Same as ParsedValue.parse */
 export async function parseValue(
   value: Json,
   source: ConfigSource,