@promptbook/markdown-utils 0.79.0 → 0.80.0-1

package/esm/typings/books/index.d.ts

@@ -16,10 +16,10 @@ declare const _default: ({
         resultingParameterName: string;
         dependentParameterNames: string[];
     }[];
-    knowledgeSources: never[];
-    knowledgePieces: never[];
     personas: never[];
     preparations: never[];
+    knowledgeSources: never[];
+    knowledgePieces: never[];
     sourceFile: string;
 } | {
     title: string;
@@ -45,10 +45,10 @@ declare const _default: ({
         };
         dependentParameterNames: string[];
     }[];
-    knowledgeSources: never[];
-    knowledgePieces: never[];
     personas: never[];
     preparations: never[];
+    knowledgeSources: never[];
+    knowledgePieces: never[];
     sourceFile: string;
 } | {
     title: string;
@@ -69,10 +69,10 @@ declare const _default: ({
         format: string;
         dependentParameterNames: string[];
     }[];
-    knowledgeSources: never[];
-    knowledgePieces: never[];
     personas: never[];
     preparations: never[];
+    knowledgeSources: never[];
+    knowledgePieces: never[];
     sourceFile: string;
 })[];
 export default _default;

package/esm/typings/src/_packages/core.index.d.ts

@@ -21,16 +21,17 @@ import { DEFAULT_BOOKS_DIRNAME } from '../config';
 import { DEFAULT_EXECUTIONS_CACHE_DIRNAME } from '../config';
 import { DEFAULT_SCRAPE_CACHE_DIRNAME } from '../config';
 import { DEFAULT_PIPELINE_COLLECTION_BASE_FILENAME } from '../config';
-import { RESERVED_PARAMETER_NAMES } from '../config';
 import { DEFAULT_REMOTE_URL } from '../config';
 import { DEFAULT_REMOTE_URL_PATH } from '../config';
 import { DEFAULT_CSV_SETTINGS } from '../config';
 import { DEFAULT_IS_VERBOSE } from '../config';
 import { SET_IS_VERBOSE } from '../config';
 import { DEFAULT_IS_AUTO_INSTALLED } from '../config';
+import { ORDER_OF_PIPELINE_JSON } from '../constants';
+import { RESERVED_PARAMETER_NAMES } from '../constants';
+import { compilePipeline } from '../conversion/compilePipeline';
 import { pipelineJsonToString } from '../conversion/pipelineJsonToString';
-import { pipelineStringToJson } from '../conversion/pipelineStringToJson';
-import { pipelineStringToJsonSync } from '../conversion/pipelineStringToJsonSync';
+import { precompilePipeline } from '../conversion/precompilePipeline';
 import { prettifyPipelineString } from '../conversion/prettify/prettifyPipelineString';
 import { extractParameterNamesFromTask } from '../conversion/utils/extractParameterNamesFromTask';
 import { removePipelineCommand } from '../conversion/utils/removePipelineCommand';
@@ -141,16 +142,17 @@ export { DEFAULT_BOOKS_DIRNAME };
 export { DEFAULT_EXECUTIONS_CACHE_DIRNAME };
 export { DEFAULT_SCRAPE_CACHE_DIRNAME };
 export { DEFAULT_PIPELINE_COLLECTION_BASE_FILENAME };
-export { RESERVED_PARAMETER_NAMES };
 export { DEFAULT_REMOTE_URL };
 export { DEFAULT_REMOTE_URL_PATH };
 export { DEFAULT_CSV_SETTINGS };
 export { DEFAULT_IS_VERBOSE };
 export { SET_IS_VERBOSE };
 export { DEFAULT_IS_AUTO_INSTALLED };
+export { ORDER_OF_PIPELINE_JSON };
+export { RESERVED_PARAMETER_NAMES };
+export { compilePipeline };
 export { pipelineJsonToString };
-export { pipelineStringToJson };
-export { pipelineStringToJsonSync };
+export { precompilePipeline };
 export { prettifyPipelineString };
 export { extractParameterNamesFromTask };
 export { removePipelineCommand };

package/esm/typings/src/_packages/types.index.d.ts

@@ -253,9 +253,12 @@ import type { string_camelCase } from '../utils/normalization/normalizeTo_camelC
 import type { string_PascalCase } from '../utils/normalization/normalizeTo_PascalCase';
 import type { string_SCREAMING_CASE } from '../utils/normalization/normalizeTo_SCREAMING_CASE';
 import type { string_snake_case } from '../utils/normalization/normalizeTo_snake_case';
+import type { OrderJsonOptions } from '../utils/normalization/orderJson';
 import type { empty_object } from '../utils/organization/empty_object';
 import type { really_any } from '../utils/organization/really_any';
 import type { TODO_any } from '../utils/organization/TODO_any';
+import type { CheckSerializableAsJsonOptions } from '../utils/serialization/checkSerializableAsJson';
+import type { ExportJsonOptions } from '../utils/serialization/exportJson';
 import type { string_promptbook_version } from '../version';
 export type { PipelineCollection };
 export type { Command };
@@ -512,7 +515,10 @@ export type { string_camelCase };
 export type { string_PascalCase };
 export type { string_SCREAMING_CASE };
 export type { string_snake_case };
+export type { OrderJsonOptions };
 export type { empty_object };
 export type { really_any };
 export type { TODO_any };
+export type { CheckSerializableAsJsonOptions };
+export type { ExportJsonOptions };
 export type { string_promptbook_version };

package/esm/typings/src/_packages/utils.index.d.ts

@@ -38,6 +38,7 @@ import type { string_SCREAMING_CASE } from '../utils/normalization/normalizeTo_S
 import { normalizeTo_SCREAMING_CASE } from '../utils/normalization/normalizeTo_SCREAMING_CASE';
 import { normalizeTo_snake_case } from '../utils/normalization/normalizeTo_snake_case';
 import { normalizeWhitespaces } from '../utils/normalization/normalizeWhitespaces';
+import { orderJson } from '../utils/normalization/orderJson';
 import { parseKeywords } from '../utils/normalization/parseKeywords';
 import { parseKeywordsFromString } from '../utils/normalization/parseKeywordsFromString';
 import { removeDiacritics } from '../utils/normalization/removeDiacritics';
@@ -54,6 +55,7 @@ import { $deepFreeze } from '../utils/serialization/$deepFreeze';
 import { checkSerializableAsJson } from '../utils/serialization/checkSerializableAsJson';
 import { clonePipeline } from '../utils/serialization/clonePipeline';
 import { deepClone } from '../utils/serialization/deepClone';
+import { exportJson } from '../utils/serialization/exportJson';
 import { isSerializableAsJson } from '../utils/serialization/isSerializableAsJson';
 import { difference } from '../utils/sets/difference';
 import { intersection } from '../utils/sets/intersection';
@@ -111,6 +113,7 @@ export type { string_SCREAMING_CASE };
 export { normalizeTo_SCREAMING_CASE };
 export { normalizeTo_snake_case };
 export { normalizeWhitespaces };
+export { orderJson };
 export { parseKeywords };
 export { parseKeywordsFromString };
 export { removeDiacritics };
@@ -127,6 +130,7 @@ export { $deepFreeze };
 export { checkSerializableAsJson };
 export { clonePipeline };
 export { deepClone };
+export { exportJson };
 export { isSerializableAsJson };
 export { difference };
 export { intersection };

package/esm/typings/src/cli/cli-commands/runInteractiveChatbot.d.ts

@@ -0,0 +1,32 @@
+import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
+import type { PipelineExecutor } from '../../execution/PipelineExecutor';
+/**
+ * Options for running the interactive chatbot
+ */
+type RunInteractiveChatbotOptions = {
+    /**
+     * Prepared pipeline to run
+     */
+    pipeline: PipelineJson;
+    /**
+     * Prepared pipeline executor
+     */
+    pipelineExecutor: PipelineExecutor;
+    /**
+     * Whether to show verbose output
+     */
+    isVerbose: boolean;
+};
+/**
+ * Run the interactive chatbot in CLI
+ *
+ * @returns Never-ending promise or process exit
+ * @private internal function of `promptbookCli` and `initializeRunCommand`
+ */
+export declare function runInteractiveChatbot(options: RunInteractiveChatbotOptions): Promise<void | never>;
+export {};
+/**
+ * TODO: Saving reports from the chatbot conversation
+ * TODO: [⛲️] This is the right place to start implementing INK
+ * Note: [🟡] Code in this file should never be published outside of `@promptbook/cli`
+ */

package/esm/typings/src/commands/_common/getParserForCommand.d.ts

@@ -6,6 +6,6 @@ import type { CommandParser } from './types/CommandParser';
  * @returns the parser for the command
  * @throws {UnexpectedError} if the parser is not found
  *
- * @private within the pipelineStringToJson
+ * @private within the compilePipeline
  */
 export declare function getParserForCommand<TCommand extends Command>(command: TCommand): CommandParser<TCommand>;

package/esm/typings/src/commands/_common/parseCommand.d.ts

@@ -7,6 +7,6 @@ import type { CommandUsagePlace } from './types/CommandUsagePlaces';
  * @returns parsed command object
  * @throws {ParseError} if the command is invalid
  *
- * @private within the pipelineStringToJson
+ * @private within the compilePipeline
  */
 export declare function parseCommand(raw: string_markdown_text, usagePlace: CommandUsagePlace): Command;

package/esm/typings/src/commands/_common/stringifyCommand.d.ts

@@ -6,6 +6,6 @@ import type { Command } from './types/Command';
  * @returns stringified command
  * @throws {UnexpectedError} if the command is invalid
  *
- * @private within the pipelineStringToJson
+ * @private within the compilePipeline
  */
 export declare function stringifyCommand(command: Command): string_markdown_text;

package/esm/typings/src/commands/_common/types/CommandParser.d.ts

@@ -65,6 +65,7 @@ export type CommonCommandParser<TCommand extends CommandBase> = {
      * Converts the command back to string
      *
      * Note: This is used in `pipelineJsonToString` utility
+     * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
      */
     stringify(command: TCommand): string_markdown_text;
 };
@@ -94,6 +95,7 @@ export type PipelineHeadCommandParser<TCommand extends CommandBase> = CommonComm
      * Reads the command from the `PipelineJson`
      *
      * Note: This is used in `pipelineJsonToString` utility
+     * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
      */
     takeFromPipelineJson(pipelineJson: PipelineJson): ReadonlyArray<TCommand>;
 };
@@ -183,4 +185,5 @@ export type CommandParserInput = {
 };
 /**
  * TODO: [♓️] Add order here
+ * TODO: [🧠][🍱] Maybe make some common abstraction between `HighLevelAbstraction` and `CommandParser`
  */

package/esm/typings/src/config.d.ts

@@ -162,30 +162,6 @@ export declare const DEFAULT_SCRAPE_CACHE_DIRNAME = "./.promptbook/scrape-cache"
  * @public exported from `@promptbook/core`
  */
 export declare const DEFAULT_PIPELINE_COLLECTION_BASE_FILENAME = "index";
-/**
- * Nonce which is used for replacing things in strings
- *
- * @private within the repository
- */
-export declare const REPLACING_NONCE = "u$k42k%!V2zo34w7Fu#@QUHYPW";
-/**
- * The names of the parameters that are reserved for special purposes
- *
- * @public exported from `@promptbook/core`
- */
-export declare const RESERVED_PARAMETER_NAMES: readonly ["content", "context", "knowledge", "examples", "modelName", "currentDate"];
-/**
- * @@@
- *
- * @private within the repository
- */
-export declare const RESERVED_PARAMETER_MISSING_VALUE: string;
-/**
- * @@@
- *
- * @private within the repository
- */
-export declare const RESERVED_PARAMETER_RESTRICTED: string;
 /**
  * The thresholds for the relative time in the `moment` NPM package.
  *
@@ -246,7 +222,6 @@ export declare const IS_PIPELINE_LOGIC_VALIDATED: boolean;
  */
 export declare const IS_COST_PREVENTED: boolean;
 /**
- * TODO: Extract `constants.ts` from `config.ts`
  * Note: [💞] Ignore a discrepancy between file name and entity name
  * TODO: [🧠][🧜‍♂️] Maybe join remoteUrl and path into single value
  */

package/esm/typings/src/constants.d.ts

@@ -0,0 +1,35 @@
+import type { PipelineJson } from './pipeline/PipelineJson/PipelineJson';
+import type { ExportJsonOptions } from './utils/serialization/exportJson';
+/**
+ * Order of keys in the pipeline JSON
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const ORDER_OF_PIPELINE_JSON: ExportJsonOptions<PipelineJson>['order'];
+/**
+ * Nonce which is used for replacing things in strings
+ *
+ * @private within the repository
+ */
+export declare const REPLACING_NONCE = "u$k42k%!V2zo34w7Fu#@QUHYPW";
+/**
+ * @@@
+ *
+ * @private within the repository
+ */
+export declare const RESERVED_PARAMETER_MISSING_VALUE: string;
+/**
+ * @@@
+ *
+ * @private within the repository
+ */
+export declare const RESERVED_PARAMETER_RESTRICTED: string;
+/**
+ * The names of the parameters that are reserved for special purposes
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const RESERVED_PARAMETER_NAMES: readonly ["content", "context", "knowledge", "examples", "modelName", "currentDate"];
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/conversion/{pipelineStringToJson.d.ts → compilePipeline.d.ts}

@@ -6,8 +6,8 @@ import type { PrepareAndScrapeOptions } from '../prepare/PrepareAndScrapeOptions
  * Compile pipeline from string (markdown) format to JSON format
  *
  * Note: There are 3 similar functions:
- * - `pipelineStringToJson` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
- * - `pipelineStringToJsonSync` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
+ * - `compilePipeline` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
+ * - `precompilePipeline` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
  * - `preparePipeline` - just one step in the compilation process
  *
  * Note: This function does not validate logic of the pipeline only the parsing
@@ -20,7 +20,7 @@ import type { PrepareAndScrapeOptions } from '../prepare/PrepareAndScrapeOptions
  * @throws {ParseError} if the promptbook string is not valid
  * @public exported from `@promptbook/core`
  */
-export declare function pipelineStringToJson(pipelineString: PipelineString, tools?: Pick<ExecutionTools, 'llm' | 'fs' | 'scrapers'>, options?: PrepareAndScrapeOptions): Promise<PipelineJson>;
+export declare function compilePipeline(pipelineString: PipelineString, tools?: Pick<ExecutionTools, 'llm' | 'fs' | 'scrapers'>, options?: PrepareAndScrapeOptions): Promise<PipelineJson>;
 /**
  * TODO: [🏏] Leverage the batch API and build queues @see https://platform.openai.com/docs/guides/batch
  * TODO: [🛠] Actions, instruments (and maybe knowledge) => Functions and tools

package/esm/typings/src/conversion/pipelineJsonToString.d.ts

@@ -3,6 +3,7 @@ import type { PipelineString } from '../pipeline/PipelineString';
 /**
  * Converts promptbook in JSON format to string format
  *
+ * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
  * @param pipelineJson Promptbook in JSON format (.book.json)
  * @returns Promptbook in string format (.book.md)
  * @public exported from `@promptbook/core`

package/esm/typings/src/conversion/{pipelineStringToJsonSync.d.ts → precompilePipeline.d.ts}

@@ -4,8 +4,8 @@ import type { PipelineString } from '../pipeline/PipelineString';
  * Compile pipeline from string (markdown) format to JSON format synchronously
  *
  * Note: There are 3 similar functions:
- * - `pipelineStringToJson` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
- * - `pipelineStringToJsonSync` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
+ * - `compilePipeline` **(preferred)** - which propperly compiles the promptbook and use embedding for external knowledge
+ * - `precompilePipeline` - use only if you need to compile promptbook synchronously and it contains NO external knowledge
  * - `preparePipeline` - just one step in the compilation process
  *
  * Note: This function does not validate logic of the pipeline only the parsing
@@ -16,8 +16,9 @@ import type { PipelineString } from '../pipeline/PipelineString';
  * @throws {ParseError} if the promptbook string is not valid
  * @public exported from `@promptbook/core`
  */
-export declare function pipelineStringToJsonSync(pipelineString: PipelineString): PipelineJson;
+export declare function precompilePipeline(pipelineString: PipelineString): PipelineJson;
 /**
+ * TODO: [🧠] Maybe more things here can be refactored as high-level abstractions
  * TODO: [main] !!!! Warn if used only sync version
  * TODO: [🚞] Report here line/column of error
  * TODO: Use spaceTrim more effectively

package/esm/typings/src/high-level-abstractions/_common/HighLevelAbstraction.d.ts

@@ -0,0 +1,20 @@
+import type { $PipelineJson } from '../../commands/_common/types/CommandParser';
+/**
+ * Used in `precompilePipeline`
+ *
+ * @private
+ */
+export type SyncHighLevelAbstraction = {
+    type: 'SYNC';
+    /**
+     * Apply the abstraction to the `pipelineJson`
+     *
+     * Note: `$` is used to indicate that this function mutates given `pipelineJson`
+     */
+    $applyToPipelineJson($pipelineJson: $PipelineJson): void;
+};
+/**
+ * TODO: [♓️] Add order here
+ * TODO: [🧠][🍱] Maybe make some common abstraction between `HighLevelAbstraction` and `CommandParser`
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/high-level-abstractions/implicit-formfactor/ImplicitFormfactorHla.d.ts

@@ -0,0 +1,10 @@
+import type { $PipelineJson } from '../../commands/_common/types/CommandParser';
+/**
+ * Set formfactor based on the pipeline interface e
+ *
+ * @private
+ */
+export declare const ImplicitFormfactorHla: {
+    type: "SYNC";
+    $applyToPipelineJson($pipelineJson: $PipelineJson): void;
+};

package/esm/typings/src/high-level-abstractions/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * All high-level abstractions
+ *
+ * @private internal index of `precompilePipeline` (= used for sync) and `preparePipeline` (= used for async)
+ */
+export declare const HIGH_LEVEL_ABSTRACTIONS: readonly [{
+    type: "SYNC";
+    $applyToPipelineJson($pipelineJson: import("type-fest/source/writable-deep").WritableObjectDeep<{
+        readonly pipelineUrl?: string | undefined;
+        readonly sourceFile?: string | undefined;
+        readonly title: string;
+        readonly bookVersion?: string | undefined;
+        readonly description?: string | undefined;
+        readonly parameters: import("../_packages/types.index").ParameterJson[];
+        readonly defaultModelRequirements?: Partial<import("../types/ModelRequirements").ModelRequirements> | undefined;
+        readonly tasks: import("../_packages/types.index").TaskJson[];
+        readonly knowledgeSources: (import("../_packages/types.index").KnowledgeSourceJson | import("../_packages/types.index").KnowledgeSourcePreparedJson)[];
+        readonly knowledgePieces: import("../_packages/types.index").KnowledgePiecePreparedJson[];
+        readonly personas: (import("../_packages/types.index").PersonaJson | import("../_packages/types.index").PersonaPreparedJson)[];
+        readonly preparations: import("../_packages/types.index").PreparationJson[];
+        readonly formfactorName?: "CHATBOT" | "GENERATOR" | "GENERIC" | "EXPERIMENTAL_MATCHER" | "SHEETS" | "TRANSLATOR" | undefined;
+    }>): void;
+}, {
+    type: "SYNC";
+    $applyToPipelineJson($pipelineJson: import("type-fest/source/writable-deep").WritableObjectDeep<{
+        readonly pipelineUrl?: string | undefined;
+        readonly sourceFile?: string | undefined;
+        readonly title: string;
+        readonly bookVersion?: string | undefined;
+        readonly description?: string | undefined;
+        readonly parameters: import("../_packages/types.index").ParameterJson[];
+        readonly defaultModelRequirements?: Partial<import("../types/ModelRequirements").ModelRequirements> | undefined;
+        readonly tasks: import("../_packages/types.index").TaskJson[];
+        readonly knowledgeSources: (import("../_packages/types.index").KnowledgeSourceJson | import("../_packages/types.index").KnowledgeSourcePreparedJson)[];
+        readonly knowledgePieces: import("../_packages/types.index").KnowledgePiecePreparedJson[];
+        readonly personas: (import("../_packages/types.index").PersonaJson | import("../_packages/types.index").PersonaPreparedJson)[];
+        readonly preparations: import("../_packages/types.index").PreparationJson[];
+        readonly formfactorName?: "CHATBOT" | "GENERATOR" | "GENERIC" | "EXPERIMENTAL_MATCHER" | "SHEETS" | "TRANSLATOR" | undefined;
+    }>): void;
+}];
+/**
+ * TODO: Test that all sync high-level abstractions are before async high-level abstractions
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/high-level-abstractions/quick-chatbot/QuickChatbotHla.d.ts

@@ -0,0 +1,10 @@
+import type { $PipelineJson } from '../../commands/_common/types/CommandParser';
+/**
+ * Allow to define chatbot with no need to write full interface
+ *
+ * @private
+ */
+export declare const QuickChatbotHla: {
+    type: "SYNC";
+    $applyToPipelineJson($pipelineJson: $PipelineJson): void;
+};

package/esm/typings/src/llm-providers/remote/RemoteLlmExecutionTools.d.ts

@@ -54,7 +54,7 @@ export declare class RemoteLlmExecutionTools<TCustomOptions = undefined> impleme
     private callCommonModel;
 }
 /**
- * TODO: Maybe use `$asDeeplyFrozenSerializableJson`
+ * TODO: Maybe use `$exportJson`
  * TODO: [🧠][🛍] Maybe not `isAnonymous: boolean` BUT `mode: 'ANONYMOUS'|'COLLECTION'`
  * TODO: [🍓] Allow to list compatible models with each variant
  * TODO: [🗯] RemoteLlmExecutionTools should extend Destroyable and implement IDestroyable

package/esm/typings/src/llm-providers/remote/startRemoteServer.d.ts

@@ -11,7 +11,7 @@ import type { RemoteServerOptions } from './interfaces/RemoteServerOptions';
  */
 export declare function startRemoteServer<TCustomOptions = undefined>(options: RemoteServerOptions<TCustomOptions>): IDestroyable;
 /**
- * TODO: Maybe use `$asDeeplyFrozenSerializableJson`
+ * TODO: Maybe use `$exportJson`
  * TODO: [🧠][🛍] Maybe not `isAnonymous: boolean` BUT `mode: 'ANONYMOUS'|'COLLECTION'`
  * TODO: [⚖] Expose the collection to be able to connect to same collection via createCollectionFromUrl
  * TODO: Handle progress - support streaming

package/esm/typings/src/prepare/prepareTasks.d.ts

@@ -22,6 +22,7 @@ type PreparedTasks = {
 export declare function prepareTasks(pipeline: PrepareTaskInput, tools: Pick<ExecutionTools, 'llm' | 'fs' | 'scrapers'>, options: PrepareAndScrapeOptions): Promise<PreparedTasks>;
 export {};
 /**
+ * TODO: [😂] Adding knowledge should be convert to async high-level abstractions, simmilar thing with expectations to sync high-level abstractions
  * TODO: [🧠] Add context to each task (if missing)
  * TODO: [🧠] What is better name `prepareTask` or `prepareTaskAndParameters`
  * TODO: [♨][main] !!! Prepare index the examples and maybe tasks

package/esm/typings/src/prepare/unpreparePipeline.d.ts

@@ -2,6 +2,7 @@ import type { PipelineJson } from '../pipeline/PipelineJson/PipelineJson';
 /**
  * Unprepare just strips the preparation data of the pipeline
  *
+ * @deprecated In future version this function will be removed or deprecated
  * @public exported from `@promptbook/core`
  */
 export declare function unpreparePipeline(pipeline: PipelineJson): PipelineJson;

package/esm/typings/src/types/typeAliases.d.ts

@@ -1,5 +1,5 @@
 import type { TupleToUnion } from 'type-fest';
-import { RESERVED_PARAMETER_NAMES } from '../config';
+import { RESERVED_PARAMETER_NAMES } from '../constants';
 /**
  * Semantic helper
  */

package/esm/typings/src/utils/normalization/orderJson.d.ts

@@ -0,0 +1,21 @@
+import type { JsonArray, JsonObject } from 'type-fest';
+/**
+ * Options for the `orderJson` function
+ */
+export type OrderJsonOptions<TObject extends JsonObject | JsonArray> = {
+    /**
+     * Value to checked, ordered and deeply frozen
+     */
+    value: TObject;
+    /**
+     * Order of the object properties
+     */
+    order: Array<keyof TObject>;
+};
+/**
+ * Orders JSON object by keys
+ *
+ * @returns The same type of object as the input re-ordered
+ * @public exported from `@promptbook/utils`
+ */
+export declare function orderJson<TObject extends JsonObject | JsonArray>(options: OrderJsonOptions<TObject>): TObject;

package/esm/typings/src/utils/normalization/orderJson.test.d.ts

@@ -0,0 +1,4 @@
+export {};
+/**
+ * TODO: [🧠] Is there a way how to test order of value better way than via `JSON.stringify`
+ */

package/esm/typings/src/utils/organization/keepTypeImported.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Just says that the type is used but `organize-imports-cli` does not recognize it.
+ * [🤛] This is a workaround for the issue.
+ *
+ * @param value any values
+ * @returns void
+ * @private within the repository
+ */
+export declare function keepTypeImported<TTypeToKeep>(): void;

package/esm/typings/src/utils/serialization/$deepFreeze.d.ts

@@ -1,6 +1,6 @@
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * @@@
+ * Freezes the given object and all its nested objects recursively
  *
  * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
  * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object

package/esm/typings/src/utils/serialization/checkSerializableAsJson.d.ts

@@ -1,4 +1,22 @@
 import type { string_name } from '../../types/typeAliases';
+import type { really_unknown } from '../organization/really_unknown';
+/**
+ * Options for the `checkSerializableAsJson` function
+ */
+export type CheckSerializableAsJsonOptions = {
+    /**
+     * Value to be checked
+     */
+    value: really_unknown;
+    /**
+     * Semantic name of the value for debugging purposes
+     */
+    name?: string_name;
+    /**
+     * Message alongside the value for debugging purposes
+     */
+    message?: string;
+};
 /**
  * Checks if the value is [🚉] serializable as JSON
  * If not, throws an UnexpectedError with a rich error message and tracking
@@ -19,9 +37,9 @@ import type { string_name } from '../../types/typeAliases';
  * @throws UnexpectedError if the value is not serializable as JSON
  * @public exported from `@promptbook/utils`
  */
-export declare function checkSerializableAsJson(name: string_name, value: unknown): void;
+export declare function checkSerializableAsJson(options: CheckSerializableAsJsonOptions): void;
 /**
- * TODO: [🧠][🛣] More elegant way to tracking than passing `name`
+ * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
  * TODO: [🧠][main] !!! In-memory cache of same values to prevent multiple checks
  * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
  */

package/esm/typings/src/utils/serialization/deepClone.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/serialization/exportJson.d.ts

@@ -0,0 +1,29 @@
+import type { JsonArray, JsonObject } from 'type-fest';
+import type { OrderJsonOptions } from '../normalization/orderJson';
+import type { CheckSerializableAsJsonOptions } from './checkSerializableAsJson';
+/**
+ * Options for the `$exportJson` function
+ */
+export type ExportJsonOptions<TObject> = CheckSerializableAsJsonOptions & Partial<Pick<OrderJsonOptions<TObject & (JsonObject | JsonArray)>, 'order'>> & {
+    /**
+     * Value to be checked, ordered and deeply frozen
+     */
+    value: TObject;
+};
+/**
+ * Utility to export a JSON object from a function
+ *
+ * 1) Checks if the value is serializable as JSON
+ * 2) Makes a deep clone of the object
+ * 2) Orders the object properties
+ * 2) Deeply freezes the cloned object
+ *
+ * Note: This function does not mutates the given object
+ *
+ * @returns The same type of object as the input but read-only and re-ordered
+ * @public exported from `@promptbook/utils`
+ */
+export declare function exportJson<TObject>(options: ExportJsonOptions<TObject>): TObject;
+/**
+ * TODO: [🧠] Is there a way how to meaningfully test this utility
+ */

package/esm/typings/src/utils/serialization/isSerializableAsJson.d.ts

@@ -1,3 +1,4 @@
+import { JsonValue } from 'type-fest';
 /**
  * Tests if the value is [🚉] serializable as JSON
  *
@@ -17,7 +18,7 @@
  *
  * @public exported from `@promptbook/utils`
  */
-export declare function isSerializableAsJson(value: unknown): boolean;
+export declare function isSerializableAsJson(value: unknown): value is JsonValue;
 /**
  * TODO: [🧠][main] !!! In-memory cache of same values to prevent multiple checks
  * TODO: [🧠][💺] Can be done this on type-level?

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/markdown-utils",
-    "version": "0.79.0",
+    "version": "0.80.0-1",
     "description": "It's time for a paradigm shift. The future of software in plain English, French or Latin",
     "--note-0": "    <- [🐊]",
     "private": false,