tw5-typed 0.3.9 → 0.3.11

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "url": "https://github.com/tiddly-gittly/tw5-typed",
   "homepage": "https://github.com/tiddly-gittly/tw5-typed",
   "bugs": {

package/src/modules/parsers/index.d.ts

@@ -9,6 +9,8 @@ declare module 'tiddlywiki' {
      */
     parseAsInline?: boolean;
     defaultType?: string;
+    parentWidget?: Widget;
+    document?: TWDocument;
   }
 
   export class WikiParseRule {

package/src/modules/server/index.d.ts

@@ -106,6 +106,12 @@ declare module 'tiddlywiki' {
     data: string;
     server: Server;
     wiki: Wiki;
+    /**
+     * With `exports.path = /^\/recipes\/default\/tiddlers\/(.+)$/;` you can use:
+     * 
+     * `title = $tw.utils.decodeURIComponentSafe(state.params[0])`
+     */
+    params: string[];
   }
   /**
    * @link https://talk.tiddlywiki.org/t/what-is-the-state-in-server-route-handler/2877

package/src/modules/utils/crypto.d.ts

@@ -0,0 +1,32 @@
+declare module '$:/core/modules/utils/crypto.js' {
+  /**
+   * Extracts an encrypted store area from a TiddlyWiki file.
+   * @param text - The text of the TiddlyWiki file.
+   * @returns The extracted encrypted store area, or null if not found.
+   */
+  export function extractEncryptedStoreArea(text: string): string | null;
+
+  /**
+   * Attempts to decrypt an encrypted store area using the provided password.
+   * @param encryptedStoreArea - The encrypted store area to decrypt.
+   * @param password - The password to use for decryption.
+   * @returns An array of decrypted tiddlers, or null if decryption fails.
+   */
+  export function decryptStoreArea(
+    encryptedStoreArea: string,
+    password?: string,
+  ): any[] | null;
+
+  /**
+   * Prompts the user for a password and attempts to decrypt an encrypted store area using the provided password.
+   * @param encryptedStoreArea - The encrypted store area to decrypt.
+   * @param callback - The function to call with the decrypted tiddlers.
+   * @param options - Configuration options.
+   * @param options.usePasswordVault - Whether to store the password in the system password vault.
+   */
+  export function decryptStoreAreaInteractive(
+    encryptedStoreArea: string,
+    callback: (tiddlers: any[]) => void,
+    options?: { usePasswordVault?: boolean },
+  ): void;
+}

package/src/modules/utils/csv.d.ts

@@ -0,0 +1,38 @@
+declare module '$:/core/modules/utils/csv.js' {
+  /**
+   * Information about a CSV cell.
+   * @property {number} start - The start index of the cell in the CSV string.
+   * @property {number} end - The end index of the cell in the CSV string.
+   * @property {boolean} isQuoted - Whether the cell is quoted.
+   * @description CSV 单元格的信息。
+   */
+  interface CellInfo {
+    start: number;
+    end: number;
+    isQuoted: boolean;
+  }
+
+  /**
+   * Parse a CSV string into an array of arrays.
+   * @param text - The CSV string to parse.
+   * @param options - The options for parsing the CSV string.
+   * @returns An array of arrays representing the CSV data.
+   * @description 将 CSV 字符串解析为数组的数组。
+   */
+  export function parseCsvString(
+    text: string,
+    options?: { separator?: string },
+  ): any[][];
+
+  /**
+   * Parse a CSV string with a header row and return an array of objects.
+   * @param text - The CSV string to parse.
+   * @param options - The options for parsing the CSV string.
+   * @returns An array of objects representing the CSV data.
+   * @description 解析具有标题行的 CSV 字符串并返回对象数组。
+   */
+  export function parseCsvStringWithHeader(
+    text: string,
+    options?: { separator?: string },
+  ): object[];
+}

package/src/modules/utils/dom.d.ts

@@ -1,35 +1,35 @@
-declare module 'tiddlywiki' {
-  import { addClass, addEventListeners } from '$:/core/modules/utils/dom.js';
-  interface IUtils {
-    /**
-     * Alternative to `element.classList.add`, add a css class name to an element, see issue for detail.
-     * @link https://github.com/Jermolene/TiddlyWiki5/issues/6475
-     * @param element
-     * @param className
-     */
-    addClass: typeof addClass;
-    /**
-     * Attach specified event handlers to a DOM node
-     * @param domNode: where to attach the event handlers
-     * @param events: array of event handlers to be added (see below)
-     * Each entry in the events array is an object with these properties:
-     * * name: event name of `addEventListener`
-     * * handlerFunction: optional event handler function
-     * * handlerObject: optional event handler object
-     * * handlerMethod: optionally specifies object handler method name (defaults to `handleEvent`)
-     */
-    addEventListeners: typeof addEventListeners;
-    /**
-     * Notifier mechanism
-     */
-    Notifier: typeof Notifier;
-    /**
-     * Copy plain text to the clipboard on browsers that support it.
-     * 
-     * And send a notification to the user if doNotNotify is not true.
-     */
-    copyToClipboard(text: string, option?: { doNotNotify?: boolean }): void;
-  }
+declare module '$:/core/modules/utils/dom.js' {
+  /**
+   * Alternative to `element.classList.add`, add a css class name to an element, see issue for detail.
+   * @link https://github.com/Jermolene/TiddlyWiki5/issues/6475
+   * @param element
+   * @param className
+   */
+  export function addClass(element: Element, className: string): void;
+
+  /**
+   * Attach specified event handlers to a DOM node
+   * @param domNode: where to attach the event handlers
+   * @param events: array of event handlers to be added (see below)
+   * Each entry in the events array is an object with these properties:
+   * * name: event name of `addEventListener`
+   * * handlerFunction: optional event handler function
+   * * handlerObject: optional event handler object
+   * * handlerMethod: optionally specifies object handler method name (defaults to `handleEvent`)
+   */
+  export function addEventListeners(
+    domNode: Element,
+    events: {
+      handlerFunction?: (event: MouseEvent) => void;
+      handlerMethod?: string;
+      handlerObject?: Widget;
+      name: string;
+    }[],
+  ): void;
+
+  /**
+   * Notifier mechanism
+   */
   export class Notifier {
     /**
      * Display a notification
@@ -40,18 +40,3 @@ declare module 'tiddlywiki' {
     display(title: string, options?: Record<string, unknown>): void;
   }
 }
-
-declare module '$:/core/modules/utils/dom.js' {
-  import { Widget, Notifier } from 'tiddlywiki';
-  export const addClass: (element: Element, className: string) => void;
-  export const addEventListeners: (
-    domNode: Element,
-    events: {
-      handlerFunction?: (event: MouseEvent) => void;
-      handlerMethod?: string;
-      handlerObject?: Widget;
-      name: string;
-    }[],
-  ) => void;
-  export { Notifier }
-}

package/src/modules/utils/edition-info.d.ts

@@ -0,0 +1,11 @@
+declare module '$:/core/modules/utils/edition-info.js' {
+  /**
+   * Get the edition information.
+   * @description 获取版本信息。
+   * @returns An object containing the edition information.
+   * @returns 包含版本信息的对象。
+   */
+  export function getEditionInfo(): {
+    [key: string]: any;
+  };
+}

package/src/modules/utils/escapecss.d.ts

@@ -0,0 +1,8 @@
+declare module '$:/core/modules/utils/escapecss.js' {
+  /**
+   * The onstalled event handler of the element
+   * @returns The escaped string
+   * @description 为在 CSS 选择器或标识符中使用而转义字符串
+   */
+  export function escapeCSS(value: string): typeof window.CSS.escape;
+}

package/src/modules/utils/fakedom.d.ts

@@ -23,5 +23,6 @@ declare module 'tiddlywiki' {
 }
 
 declare module '$:/core/modules/utils/fakedom.js' {
-  export type { TW_Element, TW_TextNode, IFakeDocument } from 'tiddlywiki';
+  import type { IFakeDocument } from 'tiddlywiki';
+  export const fakeDocument: IFakeDocument;
 }

package/src/modules/utils/filesystem.d.ts

@@ -1,48 +1,126 @@
 declare module '$:/core/modules/utils/utils.js' {
-  import { IFileInfo, Tiddler, Wiki } from 'tiddlywiki';
+  /**
+   * Return the subdirectories of a path
+   * @param dirPath - The path to the directory
+   * @returns An array of subdirectories
+   * @description 返回路径的子目录
+   */
+  export function getSubdirectories(dirPath: string): string[];
 
-  export const generateTiddlerFilepath: (
-    title: string,
-    options?: {
-      directory?: string;
-      extension?: string;
-      fileInfo?: {
-        originalpath?: string;
-        filePath?: string;
-        writeError?: boolean;
-      };
-      pathFilters?: string[];
-      wiki?: Wiki;
-    },
-  ) => string;
+  /**
+   * Recursively (and synchronously) copy a directory and all its content
+   * @param srcPath - The source path of the directory to copy
+   * @param dstPath - The destination path of the directory to copy
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地（同步地）复制目录及其所有内容
+   */
+  export function copyDirectory(srcPath: string, dstPath: string): string;
+
+  /**
+   * Copy a file
+   * @param srcPath - The source path of the file to copy
+   * @param dstPath - The destination path of the file to copy
+   * @returns An error message if there is an error, otherwise null
+   * @description 复制文件
+   */
+  export function copyFile(srcPath: string, dstPath: string): string;
+
+  /**
+   * Remove trailing path separator
+   * @param dirPath - The directory path to remove the trailing separator from
+   * @returns The directory path without the trailing separator
+   * @description 移除路径末尾的分隔符
+   */
+  export function removeTrailingSeparator(dirPath: string): string;
+
+  /**
+   * Recursively create a directory
+   * @param dirPath - The path of the directory to create
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地创建目录
+   */
+  export function createDirectory(dirPath: string): string;
+
+  /**
+   * Recursively create directories needed to contain a specified file
+   * @param filePath - The path of the file to create directories for
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地创建包含指定文件的目录
+   */
+  export function createFileDirectories(filePath: string): string;
+
+  /**
+   * Recursively delete a directory
+   * @param dirPath - The path of the directory to delete
+   * @returns An error message if there is an error, otherwise null
+   * @description 递归地删除目录
+   */
+  export function deleteDirectory(dirPath: string): string;
+
+  /**
+   * Check if a path identifies a directory
+   * @param dirPath - The path to check
+   * @returns True if the path identifies a directory, false otherwise
+   * @description 检查路径是否标识目录
+   */
+  export function isDirectory(dirPath: string): boolean;
+
+  /**
+   * Check if a path identifies a directory that is empty
+   * @param dirPath - The path to check
+   * @returns True if the path identifies an empty directory, false otherwise
+   * @description 检查路径是否标识空目录
+   */
+  export function isDirectoryEmpty(dirPath: string): boolean;
+
+  /**
+   * Recursively delete a tree of empty directories
+   * @param dirpath - The path of the directory to delete
+   * @param callback - A callback function to call when the operation is complete
+   * @description 递归地删除空目录树
+   */
+  export function deleteEmptyDirs(
+    dirpath: string,
+    callback: (err: Error | null) => void,
+  ): void;
+
+  /**
+   * Generate a fileInfo object for saving a tiddler
+   * @param tiddler - The tiddler to generate the fileInfo for
+   * @param options - Options for generating the fileInfo
+   * @returns A fileInfo object
+   * @description 生成用于保存 tiddler 的 fileInfo 对象
+   */
   export function generateTiddlerFileInfo(
     tiddler: Tiddler,
     options: {
-      directory?: string;
+      directory: string;
       pathFilters?: string[];
       extFilters?: string[];
       wiki?: Wiki;
-      fileInfo?: IFileInfo;
+      fileInfo?: FileInfo;
     },
-  ): IFileInfo;
-}
+  ): FileInfo;
+
+  /**
+   * Generate the file extension for saving a tiddler
+   * @param title - The title of the tiddler
+   * @param options - Options for generating the file extension
+   * @returns The file extension
+   * @description 生成用于保存 tiddler 的文件扩展名
+   * 可选项包括：
+   * extFilters：用于生成扩展名的可选过滤器数组
+   * wiki：用于评估 extFilters 的可选 wiki
+   */
+  export function generateTiddlerExtension(
+    title: string,
+    options: {
+      extFilters?: string[];
+      wiki?: Wiki;
+    },
+  ): string;
 
 declare module 'tiddlywiki' {
-  import { generateTiddlerFileInfo, generateTiddlerFilepath } from '$:/core/modules/utils/utils.js';
-  export interface IFileInfo {
-    isEditableFile: boolean;
-    originalpath: string;
-    type: string;
-    hasMetaFile: boolean;
-    encoding: string;
-    filepath: string;
-  }
-  export interface ITiddlersInFile {
-    filepath: string;
-    type: string;
-    tiddlers: ITiddlerFields[];
-    hasMetaFile: boolean;
-  }
   interface IUtils {
     /**
      * Generate the filepath for saving a tiddler
@@ -54,19 +132,9 @@ declare module 'tiddlywiki' {
      * * fileInfo: an existing fileInfo object to check against
      */
     generateTiddlerFilepath: typeof generateTiddlerFilepath;
-    /**
-    Create a fileInfo object for saving a tiddler:
-      filepath: the absolute path to the file containing the tiddler
-      type: the type of the tiddler file on disk (NOT the type of the tiddler)
-      hasMetaFile: true if the file also has a companion .meta file
-      isEditableFile: true if the tiddler was loaded via non-standard options & marked editable
-    Options include:
-      directory: absolute path of root directory to which we are saving
-      pathFilters: optional array of filters to be used to generate the base path
-      extFilters: optional array of filters to be used to generate the base path
-      wiki: optional wiki for evaluating the pathFilters,
-      fileInfo: an existing fileInfo to check against
-    */
-    generateTiddlerFileInfo: typeof generateTiddlerFileInfo;
   }
 }
+
+declare module '$:/core/modules/utils/utils.js' {
+  export { generateTiddlerFilepath };
+}

package/src/modules/utils/index.d.ts

@@ -2,4 +2,34 @@
 /// <reference path="utils.d.ts" />
 /// <reference path="fakedom.d.ts" />
 /// <reference path="filesystem.d.ts" />
-/// <reference path="logger.d.ts" />
+
+declare module 'tiddlywiki' {
+  // Thanks for GitHub Copilot, you has helped me a lot!
+  import * as dom from '$:/core/modules/utils/dom.js';
+  import * as utils from '$:/core/modules/utils/utils.js';
+  import * as filesystem from '$:/core/modules/utils/filesystem.js';
+  import * as LinkedList from '$:/core/modules/utils/linked-list.js';
+  import * as performance from '$:/core/modules/utils/performance.js';
+  import * as logger from '$:/core/modules/utils/logger.js';
+  import * as parsetree from '$:/core/modules/utils/parsetree.js';
+  import * as pluginMaker from '$:/core/modules/utils/pluginmaker.js';
+  import * as transliterate from '$:/core/modules/utils/transliterate.js';
+  import * as crypto from '$:/core/modules/utils/crypto.js';
+  import * as csv from '$:/core/modules/utils/csv.js';
+  import * as editionInfo from '$:/core/modules/utils/edition-info.js';
+  import * as escapecss from '$:/core/modules/utils/escapecss.js';
+
+  type IUtilsModules = Pick<typeof dom, keyof typeof dom> &
+    Partial<Pick<typeof filesystem, keyof typeof filesystem>> &
+    Pick<typeof utils, keyof typeof utils> &
+    Pick<typeof LinkedList, keyof typeof LinkedList> &
+    Pick<typeof performance, keyof typeof performance> &
+    Pick<typeof logger, keyof typeof logger> &
+    Pick<typeof parsetree, keyof typeof parsetree> &
+    Pick<typeof pluginMaker, keyof typeof pluginMaker> &
+    Pick<typeof transliterate, keyof typeof transliterate> &
+    Pick<typeof crypto, keyof typeof crypto> &
+    Pick<typeof csv, keyof typeof csv> &
+    Pick<typeof editionInfo, keyof typeof editionInfo> &
+    Pick<typeof escapecss, keyof typeof escapecss>;
+}

package/src/modules/utils/linked-list.d.ts

@@ -0,0 +1,91 @@
+declare module '$:/core/modules/utils/linked-list.js' {
+  /**
+   * A linked list implementation.
+   * @description 链表实现。
+   */
+  export class LinkedList {
+    /**
+     * The next node in the linked list.
+     */
+    next: LLMap;
+    /**
+     * The previous node in the linked list.
+     */
+    prev: LLMap;
+    /**
+     * The length of the linked list.
+     */
+    length: number;
+    constructor();
+    /**
+     * Clear the linked list.
+     * @description 清空链表。
+     */
+    clear(): void;
+    /**
+     * Remove a value from the linked list.
+     * @param value - The value to remove.
+     * @description 从链表中删除值。
+     */
+    remove(value: string | string[]): void;
+    /**
+     * Push a value to the end of the linked list.
+     * @param values - The values to push.
+     * @returns The length of the linked list.
+     * @description 将值推送到链表的末尾。
+     */
+    push(...values: string[] | string[][]): number;
+    /**
+     * Push a value to the top of the linked list.
+     * @param value - The value to push.
+     * @description 将值推送到链表的顶部。
+     */
+    pushTop(value: string | string[]): void;
+    /**
+     * Iterate over each value in the linked list.
+     * @param callback - The callback function to call for each value.
+     * @description 迭代链表中的每个值。
+     */
+    each(callback: (value: string) => void): void;
+    /**
+     * Convert the linked list to an array.
+     * @returns The array representation of the linked list.
+     * @description 将链表转换为数组。
+     */
+    toArray(): string[];
+    /**
+     * Create an iterator for the linked list.
+     * @param wiki - The wiki to use for the iterator.
+     * @returns The iterator function.
+     * @description 创建链表的迭代器。
+     */
+    makeTiddlerIterator(
+      wiki: any,
+    ): (callback: (tiddler: any, title: string) => void) => void;
+  }
+
+  class LLMap {
+    /**
+     * The map object.
+     */
+    map: { [key: string]: any };
+    /**
+     * The null value of the map.
+     */
+    null: any;
+    /**
+     * Set a value in the map.
+     * @param key - The key to set.
+     * @param val - The value to set.
+     * @description 在映射中设置值。
+     */
+    set(key: string | null, val: any): void;
+    /**
+     * Get a value from the map.
+     * @param key - The key to get.
+     * @returns The value of the key.
+     * @description 从映射中获取值。
+     */
+    get(key: string | null): any;
+  }
+}

package/src/modules/utils/logger.d.ts

@@ -1,23 +1,84 @@
-declare module 'tiddlywiki' {
+declare module '$:/core/modules/utils/logger.js' {
+  /**
+   * A logger utility.
+   * @description 日志记录实用程序。
+   */
   export class Logger {
-    new (): Logger;
+    /**
+     * The name of the component.
+     */
+    componentName: string;
+    /**
+     * The color of the logger.
+     */
+    colour: string;
+    /**
+     * Whether the logger is enabled.
+     */
+    enable: boolean;
+    /**
+     * Whether to save the log.
+     */
+    save: boolean;
+    /**
+     * The save limit of the logger.
+     */
+    saveLimit: number;
+    /**
+     * The logger to save the buffer.
+     */
+    saveBufferLogger: Logger;
+    /**
+     * The buffer of the logger.
+     */
+    buffer: string;
+    /**
+     * The alert count of the logger.
+     */
+    alertCount: number;
+    constructor(
+      componentName?: string,
+      options?: {
+        colour?: string;
+        enable?: boolean;
+        save?: boolean;
+        saveLimit?: number;
+      },
+    );
+    /**
+     * Set the logger to save the buffer.
+     * @param logger - The logger to save the buffer.
+     * @description 设置记录器以保存缓冲区。
+     */
     setSaveBuffer(logger: Logger): void;
     /**
-      Log a message
-    */
-    log: typeof console.log;
-    clearAlerts(): void;
+     * Log a message.
+     * @param args - The arguments to log.
+     * @description 记录消息。
+     */
+    log(...args: any[]): void;
+    /**
+     * Get the message buffer.
+     * @returns The message buffer.
+     * @description 获取消息缓冲区。
+     */
     getBuffer(): string;
-    table: typeof console.table;
     /**
-      Alert a message
-    */
+     * Log a structure as a table.
+     * @param value - The value to log.
+     * @description 将结构记录为表格。
+     */
+    table(value: any): void;
+    /**
+     * Alert a message.
+     * @param args - The arguments to alert.
+     * @description 警报消息。
+     */
     alert(...args: any[]): void;
-  }
-  interface IUtils {
     /**
-     * A basic logging implementation
+     * Clear outstanding alerts.
+     * @description 清除未处理的警报。
      */
-    Logger: { new(loggerName: string): Logger};
+    clearAlerts(): void;
   }
 }