tw5-typed 0.1.12 → 0.2.2

package/package.json

@@ -2,7 +2,7 @@
   "description": "Types for tiddlywiki",
   "license": "MIT",
   "name": "tw5-typed",
-  "version": "0.1.12",
+  "version": "0.2.2",
   "url": "https://github.com/tiddly-gittly/tw5-typed",
   "homepage": "https://github.com/tiddly-gittly/tw5-typed",
   "bugs": {
@@ -20,28 +20,28 @@
     "prepublishOnly": "npx tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^17.0.22",
-    "@typescript-eslint/eslint-plugin": "5.16.0",
-    "@typescript-eslint/parser": "5.16.0",
-    "eslint": "8.11.0",
+    "@types/node": "^17.0.24",
+    "@typescript-eslint/eslint-plugin": "5.19.0",
+    "@typescript-eslint/parser": "5.19.0",
+    "eslint": "8.13.0",
     "eslint-config-prettier": "8.5.0",
     "eslint-config-standard": "16.0.3",
     "eslint-config-standard-with-typescript": "21.0.1",
     "eslint-import-resolver-alias": "1.1.2",
-    "eslint-import-resolver-typescript": "2.5.0",
+    "eslint-import-resolver-typescript": "2.7.1",
     "eslint-plugin-html": "6.2.0",
-    "eslint-plugin-import": "2.25.4",
-    "eslint-plugin-n": "15.0.1",
+    "eslint-plugin-import": "2.26.0",
+    "eslint-plugin-n": "15.1.0",
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-prettier": "4.0.0",
     "eslint-plugin-promise": "6.0.0",
     "eslint-plugin-react": "7.29.4",
-    "eslint-plugin-react-hooks": "4.3.0",
+    "eslint-plugin-react-hooks": "4.4.0",
     "eslint-plugin-security": "1.4.0",
     "eslint-plugin-security-node": "1.1.1",
     "eslint-plugin-typescript-sort-keys": "2.1.0",
-    "eslint-plugin-unicorn": "41.0.1",
-    "prettier": "2.6.0",
-    "typescript": "4.6.2"
+    "eslint-plugin-unicorn": "42.0.0",
+    "prettier": "2.6.2",
+    "typescript": "4.6.3"
   }
 }

package/src/Tiddler.d.ts

@@ -1,6 +1,10 @@
 declare module 'tiddlywiki' {
   export class Tiddler {
-    constructor(...fields: Array<Record<string, unknown> | Tiddler>);
+    /**
+     *
+     * @param tiddlers multiple tiddler fields or instances, will merge them to create a new one
+     */
+    constructor(...tiddlers: Array<Record<string, unknown> | Tiddler>);
     readonly cache: ITiddlerCache;
     readonly fields: ITiddlerFields;
     static fieldModules: Record<string, IModuleInfo>;
@@ -10,9 +14,9 @@ declare module 'tiddlywiki' {
 
   export interface ITiddlerFields {
     readonly [anyKey: string]: unknown;
-    readonly color: string;
+    readonly color?: string;
     readonly created: Date;
-    readonly list: string[];
+    readonly list?: string[];
     readonly modified: Date;
     readonly tags: string[];
     readonly text: string;

package/src/Wiki.d.ts

@@ -10,7 +10,7 @@ declare module 'tiddlywiki' {
      */
     constructor(options: { enableIndexers: unknown[] });
     addIndexer(indexer: unknown, name: string): void;
-    getTiddler: (title: string) => Tiddler | undefined;
+    getTiddler: <T extends Tiddler>(title: string) => T | undefined;
     /**
      * Get full list of tiddler titles in the wiki
      */
@@ -22,13 +22,18 @@ declare module 'tiddlywiki' {
     compileFilter: (filterString: string) => (iterator?: SourceIterator) => string[];
     /**
      * Set JSON tiddler, Object in data field will be JSON.stringify and put into the text.
+     * This will make tiddler to be JSON data tiddler `"type":"application/json"`, so if you just want to modify existed tiddler's data, use `addTiddler` instead.
      */
     setTiddlerData: (title: string, data?: object, fields?: ITiddlerFields, options?: any) => void;
     /**
      * Create or update tiddler.
      * Update existed tiddler based on the title field.
      */
-    addTiddler: (tiddler: Tiddler | ITiddlerFields) => void;
+    addTiddler: (tiddler: Tiddler | Partial<ITiddlerFields>) => void;
+    /**
+     * Call `addTiddler` for each iton of the list, but should passing `tiddler.fields`, directly passing tiddler object may failed to add in some cases.
+     */
+    addTiddlers: (tiddler: Array<Partial<ITiddlerFields>>) => void;
     /**
      * Get tiddler's text field, with an optional default text.
      * If have _is_skinny field, will just return null (this is a rare case, so not put in the return type for now).
@@ -38,6 +43,36 @@ declare module 'tiddlywiki' {
      */
     getTiddlerText(title: string, fallbackText: string): string;
     getTiddlerText(title: string, fallbackText?: string): string | undefined;
+    /**
+      Get the content of a tiddler as a JavaScript object. How this is done depends on the type of the tiddler:
+
+      application/json: the tiddler JSON is parsed into an object
+      application/x-tiddler-dictionary: the tiddler is parsed as sequence of name:value pairs
+
+      Other types currently just return undefined or as same as fallbackData.
+
+      titleOrTiddler: string tiddler title or a tiddler object
+      defaultData: default data to be returned if the tiddler is missing or doesn't contain data
+
+      Alternative, uncached version of getTiddlerDataCached(). The return value can be mutated freely and reused
+    */
+    getTiddlerData<D extends Record<string, unknown> | undefined>(titleOrTiddler: string, fallbackData?: D): D;
+    getTiddlerData<D extends Record<string, unknown> | undefined>(titleOrTiddler: Tiddler, fallbackData?: D): D;
+    /**
+      Get the content of a tiddler as a JavaScript object. How this is done depends on the type of the tiddler:
+
+      application/json: the tiddler JSON is parsed into an object
+      application/x-tiddler-dictionary: the tiddler is parsed as sequence of name:value pairs
+
+      Other types currently just return undefined or as same as fallbackData.
+
+      titleOrTiddler: string tiddler title or a tiddler object
+      defaultData: default data to be returned if the tiddler is missing or doesn't contain data
+
+      Note that the same value is returned for repeated calls for the same tiddler data. The value is frozen to prevent modification; otherwise modifications would be visible to all callers
+    */
+    getTiddlerDataCached<D extends Record<string, unknown> | undefined>(titleOrTiddler: string, fallbackData?: D): D;
+    getTiddlerDataCached<D extends Record<string, unknown> | undefined>(titleOrTiddler: Tiddler, fallbackData?: D): D;
     /**
      * Set tiddler text of any field.
      *
@@ -50,5 +85,19 @@ declare module 'tiddlywiki' {
     setText: (title: string, field?: string, index?: string | undefined, value?: string, options?: any) => void;
     parseTiddler(title: string, options?: IParserOptions): WikiParser;
     parseText(type: string, text: string, options?: IParserOptions): WikiParser;
+    /*
+      Parse text from a tiddler and render it into another format
+        outputType: content type for the output
+        title: title of the tiddler to be rendered
+        options: see below
+      Options include:
+      variables: hashmap of variables to set
+      parentWidget: optional parent widget for the root node
+      */
+    renderTiddler(
+      outputType: 'text/html' | 'text/plain-formatted' | 'text/plain',
+      title: string,
+      options?: { parentWidget?: Widget; variables?: Record<string, any> },
+    ): string;
   }
 }

package/src/ast.d.ts

@@ -1,38 +1,37 @@
 declare module 'tiddlywiki' {
   export interface IParseTreeAttribute {
-    start?: number;
+    end?: number;
     name?: string;
+    start?: number;
     type: 'string' | 'number';
     value: string;
-    end?: number;
   }
 
   export interface IWikiASTNode {
-    type: string;
+    attributes?: Record<string, IParseTreeAttribute>;
     children?: IParseTreeNode[];
-    start?: number;
     end?: number;
     isBlock?: boolean;
     isSelfClosing?: boolean;
-    attributes?: Record<string, IParseTreeAttribute>;
     orderedAttributes?: IParseTreeAttribute[];
+    start?: number;
+    type: string;
   }
   export interface ITextParseTreeNode extends IWikiASTNode {
-    type: 'text';
     text: string;
+    type: 'text';
   }
   export interface ILinkParseTreeNode extends IWikiASTNode {
-    type: 'link';
     text: string;
+    type: 'link';
   }
   export type HTMLTags = keyof HTMLElementTagNameMap | 'strike';
 
   export interface IDomParseTreeNode extends IWikiASTNode {
-    type: 'element';
     tag: HTMLTags;
+    type: 'element';
   }
   export interface ICodeBlockParseTreeNode extends IWikiASTNode {
-    type: 'codeblock';
     attributes: {
       code?:
         | {
@@ -47,22 +46,23 @@ declare module 'tiddlywiki' {
           }
         | undefined;
     };
+    type: 'codeblock';
   }
-  export interface IMacroParamCallParseTreeNode extends IWikiASTNode {
+  export interface IMacroParameterCallParseTreeNode extends IWikiASTNode {
+    name?: string;
     type: 'macro-parameter';
     value: string;
-    name?: string;
   }
   export interface IMacroCallParseTreeNode extends IWikiASTNode {
-    type: 'macrocall';
     name: string;
-    params: IMacroParamCallParseTreeNode[];
+    params: IMacroParameterCallParseTreeNode[];
+    type: 'macrocall';
   }
   export interface ICustomParseTreeNode extends IWikiASTNode {
-    type: string;
+    params: IMacroParameterCallParseTreeNode[];
     tag?: string;
-    params: IMacroParamCallParseTreeNode[];
     text?: string;
+    type: string;
   }
-  export type IParseTreeNode = IDomParseTreeNode | IMacroParamCallParseTreeNode | IMacroCallParseTreeNode | ITextParseTreeNode | ICustomParseTreeNode;
+  export type IParseTreeNode = IDomParseTreeNode | IMacroParameterCallParseTreeNode | IMacroCallParseTreeNode | ITextParseTreeNode | ICustomParseTreeNode;
 }

package/src/filter-operator.d.ts

@@ -93,7 +93,10 @@ Either way, we could interpret the `!` flag on the filter, if present, to mean t
 As with [JavaScript Macros](#JavaScript%20Macros), filter operators should not make modifications to tiddlers, but only return a list of tiddlers or a tiddler iterator.
 
    */
-  export type IFilterOperator = (source: (iter: SourceIterator) => void, operator: IFilterOperatorParameterOperator) => string[] | ((iter: SourceIterator) => void);
+  export type IFilterOperator = (
+    source: (iter: SourceIterator) => void,
+    operator: IFilterOperatorParameterOperator,
+  ) => string[] | ((iter: SourceIterator) => void);
 
   /**
    * A [tiddler iterator](#Tiddler%20Iterators) representing the results of the previous filter step (or all tiddlers, if this filter appears first in an expression), conventionally named `source`.

package/src/index.d.ts

@@ -1,24 +1,19 @@
 /// <reference path="tw.d.ts" />
-
-export * from 'tiddlywiki';
+/// <reference path="server.d.ts" />
 
 import * as TW from 'tiddlywiki';
 
-import '@types/node';
+export * from 'tiddlywiki';
 declare global {
-    const $tw: TW.ITiddlyWiki;
-    // const Buffer: ?Buffer;
-    // const clearInterval: typeof global.clearInterval;
-    // const clearTimeout: typeof global.clearTimeout;
-    // const console: Console;
-    // const exports: TW.ITWModuleExports;
-    // const module: { exports: TW.ITWModuleExports; readonly id: string };
-    // const process: ?NodeJS.Process;
-    // const require: ITWRequire;
-    // const setInterval: typeof global.setInterval;
-    // const setTimeout: typeof global.setTimeout;
-}
-
-declare module '@types/tiddlywiki' {
-  export const TiddlyWiki: TW.TW5InitFunction;
+  const $tw: TW.ITiddlyWiki;
+  // const Buffer: ?Buffer;
+  // const clearInterval: typeof global.clearInterval;
+  // const clearTimeout: typeof global.clearTimeout;
+  // const console: Console;
+  // const exports: TW.ITWModuleExports;
+  // const module: { exports: TW.ITWModuleExports; readonly id: string };
+  // const process: ?NodeJS.Process;
+  // const require: ITWRequire;
+  // const setInterval: typeof global.setInterval;
+  // const setTimeout: typeof global.setTimeout;
 }

package/src/modules.d.ts

@@ -69,7 +69,7 @@ declare module 'tiddlywiki' {
      * @param {(title, moduleExports) => void} callback function called as callback(title,moduleExports) for each module
      * @memberof ITWModules
      */
-    forEachModuleOfType(moduleType: string, callback: (title, moduleExports) => void): void;
+    forEachModuleOfType(moduleType: string, callback: (title: string, moduleExports: unknown) => void): void;
     /** Get all the modules of a particular type in a hashmap by their `name` field */
     getModulesByTypeAsHashmap(moduleType: string, nameField: string): Record<string, IModuleInfo>;
     /** hashmap by module name of moduleInfo */

package/src/parser.d.ts

@@ -2,14 +2,14 @@
 
 declare module 'tiddlywiki' {
   export interface IParserOptions {
-    /**
-     * While calling `getCacheForTiddler`, use inlineParseTree or blockParseTree
-     */
-    parseAsInline?: boolean;
     /**
      * Optional source uri, used in parseText
      */
     _canonical_uri?: string;
+    /**
+     * While calling `getCacheForTiddler`, use inlineParseTree or blockParseTree
+     */
+    parseAsInline?: boolean;
   }
 
   export class WikiParseRule {
@@ -20,18 +20,18 @@ declare module 'tiddlywiki' {
     nextTag?: null;
     /** `{type: 'macrocall', start: 261, params: Array(1), name: 'reuse-tiddler', end: 290}` */
     nextCall?: {
-      type: string;
-      start: number;
       end: number;
-      /** `{ type: 'macro-parameter'; start: 276; value: '快速创建新笔记按钮'; end: 288 }` */
-      params: { type: string; start: number; end: number; value: string };
       name: string;
+      /** `{ type: 'macro-parameter'; start: 276; value: '快速创建新笔记按钮'; end: 288 }` */
+      params: { end: number; start: number; type: string; value: string };
+      start: number;
+      type: string;
     };
   }
   export class WikiParser {
-    blockRules: { rule: WikiParseRule; matchIndex?: number }[];
-    inlineRules: { rule: WikiParseRule; matchIndex?: number }[];
-    pragmaRules: { rule: WikiParseRule; matchIndex?: number }[];
+    blockRules: Array<{ matchIndex?: number; rule: WikiParseRule }>;
+    inlineRules: Array<{ matchIndex?: number; rule: WikiParseRule }>;
+    pragmaRules: Array<{ matchIndex?: number; rule: WikiParseRule }>;
     configTrimWhiteSpace: boolean;
     pos: number;
     source: string;

package/src/server.d.ts

@@ -0,0 +1,105 @@
+/// <reference path="Wiki.d.ts" />
+
+import type Http from 'http';
+
+declare module 'tiddlywiki' {
+  export interface IServerStatus {
+    anonymous: boolean;
+    read_only: boolean;
+    space: {
+      recipe: string;
+    };
+    tiddlywiki_version: string;
+    username: string;
+  }
+
+  export interface IRoute {
+    handler: ServerEndpointHandler;
+    method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'OPTIONS' | 'HEAD';
+    path: RegExp;
+  }
+
+  export interface IServerOptions {
+    routes: IRoute[];
+    variables?: { [key: string]: string };
+    wiki: Wiki;
+  }
+
+  /**
+    A simple HTTP server with regexp-based routes
+
+    options: variables - optional hashmap of variables to set (a misnomer - they are really constant parameters)
+        routes - optional array of routes to use
+        wiki - reference to wiki object
+  */
+  export class Server {
+    constructor(options: IServerOptions);
+    routes: IRoute[];
+    addRoute(route: IRoute): void;
+    /**
+     * ```json
+     * {
+          port: "8080",
+          host: "127.0.0.1",
+          "required-plugins": "$:/plugins/tiddlywiki/filesystem,$:/plugins/tiddlywiki/tiddlyweb",
+          "root-tiddler": "$:/core/save/all",
+          "root-render-type": "text/plain",
+          "root-serve-type": "text/html",
+          "tiddler-render-type": "text/html",
+          "tiddler-render-template": "$:/core/templates/server/static.tiddler.html",
+          "system-tiddler-render-type": "text/plain",
+          "system-tiddler-render-template": "$:/core/templates/wikified-tiddler",
+          "debug-level": "none",
+          "gzip": "no",
+          "use-browser-cache": "no"
+        }
+        ```
+     */
+    defaultVariables: {
+      'debug-level': string;
+      gzip: string;
+      host: string;
+      port: string;
+      'required-plugins': string;
+      'root-render-type': string;
+      'root-serve-type': string;
+      'root-tiddler': string;
+      'system-tiddler-render-template': string;
+      'system-tiddler-render-type': string;
+      'tiddler-render-template': string;
+      'tiddler-render-type': string;
+      'use-browser-cache': string;
+    };
+
+    variables: Record<string, any>;
+    get(variableName: string): any;
+    requestHandler: ServerEndpointHandler;
+    /*
+      Listen for requests
+      port: optional port number (falls back to value of "port" variable)
+      host: optional host address (falls back to value of "host" variable)
+      prefix: optional prefix (falls back to value of "path-prefix" variable)
+      */
+    listen(port?: string, host?: string, prefix?: string): void;
+    /*
+      Check whether a given user is authorized for the specified authorizationType ("readers" or "writers"). Pass null or undefined as the username to check for anonymous access
+    */
+    isAuthorized(authorizationType: 'readers' | 'writers', username?: string | undefined): boolean;
+    close(): void;
+  }
+
+  export interface ServerEndpointContext {
+    authenticatedUsername: string | undefined;
+    data: string;
+    server: Server;
+    wiki: Wiki;
+  }
+  /**
+   * @link https://talk.tiddlywiki.org/t/what-is-the-state-in-server-route-handler/2877
+   */
+  export type ServerEndpointHandler<T = Record<string, unknown>> = (
+    request: Http.ClientRequest,
+    response: Http.ServerResponse,
+    context: ServerEndpointContext & T,
+  ) => void;
+}

package/src/tw.d.ts

@@ -8,6 +8,8 @@
 /// <reference path="parser.d.ts" />
 /// <reference path="ast.d.ts" />
 
+import { Server } from 'http';
+
 declare module 'tiddlywiki' {
   export interface IBootFilesIndexItem {
     filepath: string;
@@ -24,8 +26,6 @@ declare module 'tiddlywiki' {
     tiddlers: ITiddlerFields[];
   }
 
-  export class Server {}
-
   export interface IFileExtensionInfo {
     type: string;
   }
@@ -43,11 +43,11 @@ declare module 'tiddlywiki' {
 
     boot: {
       argv: string[];
+      boot(callback?: () => unknown): void;
       files: IBootFilesIndex;
       log(logString: string): void;
       logMessages: string[];
       startup(options: { callback?: () => unknown }): void;
-      boot(callback?: () => unknown): void;
       /** Default boot tasks */
       tasks: {
         readBrowserTiddlers: boolean;

package/src/utils.d.ts

@@ -6,15 +6,15 @@ declare module 'tiddlywiki' {
   export type TWDOMElement = Element;
   export type TWEachCallback<T> = (element?: unknown, index?: string | number, object?: T) => boolean | undefined;
   export interface ITWUtils {
+    Crypto: typeof Crypto;
+    PasswordPrompt: typeof PasswordPrompt;
     /**
      * 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 
+     * @param element
+     * @param className
      */
     addClass(element: Element, className: string): void;
-    Crypto: typeof Crypto;
-    PasswordPrompt: typeof PasswordPrompt;
     /** Returns true if the version string A is greater than the version string B. Returns true if the versions are the same */
     checkVersions(versionStringA: string, versionStringB: string): boolean;
     /**
@@ -26,6 +26,8 @@ declare module 'tiddlywiki' {
     decodeURIComponentSafe(uri: string): string;
     /** Convert a URI encoded string to a string safely */
     decodeURISafe(uri: string): string;
+    /** the function behind `<<now "format">> */
+    formatDateString(date: Date, format: string): string;
     /** Fill in any null or undefined properties of an object with the properties from a list of source objects. Each property that is an object is called recursively */
     deepDefaults(object: object, ...sourceObjectList: object[]): object;
     /**
@@ -102,6 +104,7 @@ declare module 'tiddlywiki' {
     parseDate(value: string | Date): Date;
     /** Parse a block of name:value fields. The `fields` object is used as the basis for the return value */
     parseFields(text: string, fields?: object): object;
+    parseJSONSafe(input: string): any;
     /** Parse a string array from a bracketted list. For example "OneTiddler [[Another Tiddler]] LastOne" */
     parseStringArray(value: string | string[], allowDuplicate?: boolean): string[];
     /** Parse a semantic version string into its constituent parts -- see https://semver.org */

package/src/widget.d.ts

@@ -8,6 +8,29 @@ declare module 'tiddlywiki' {
     modified: boolean;
   }
 
+  export interface IWidgetEvent {
+    /** widget event can carry any other parameters
+     *
+     * For example, `<$action-sendmessage $message="tw-mobile-sync-set-active-server-and-sync" title={{!!title}} />` will produce `paramObject: { title: "xxxx" }`
+     */
+    paramObject?: {
+      [othersParamKeys: string]: unknown;
+    };
+    /**
+     * Get `$param`
+     */
+    param?: string | undefined;
+    /** the first parameter of addEventListener
+     *
+     * For example, the `'open-command-palette'` in `$tw.rootWidget.addEventListener('open-command-palette', (e: IWidgetEvent) => this.openPalette(e));`
+     */
+    type: string;
+    widget: Widget;
+    /** maybe a DOM click event, if trigger by button click */
+    event: Event;
+    navigateFromTitle?: string;
+  }
+
   // eslint-disable-next-line @typescript-eslint/no-extraneous-class
   class variablesConstructor {}
 
@@ -24,17 +47,17 @@ declare module 'tiddlywiki' {
     variables: unknown;
     domNodes: Node[];
     /**
-    Add an event listener
-  */
-    addEventListener(type: string, handler: (arguments_: unknown[]) => void): void;
+      Add an event listener
+    */
+    addEventListener(type: string, handler: (event: IWidgetEvent) => void | Promise<void>): void;
     /**
-    Dispatch an event to a widget. If the widget doesn't handle the event then it is also dispatched to the parent widget
-  */
-    dispatchEvent(type: string): void;
+      Dispatch an event to a widget. If the widget doesn't handle the event then it is also dispatched to the parent widget
+    */
+    dispatchEvent(typeOrEvent: string | Omit<IWidgetEvent, 'widget'>): void;
     /**
-    Add a list of event listeners from an array [{type:,handler:},...]
-  */
-    addEventListeners(listeners: Array<{ handler: (arguments_: unknown[]) => void; type: string }>): void;
+      Add a list of event listeners from an array [{type:,handler:},...]
+    */
+    addEventListeners(listeners: Array<{ handler: (event: IWidgetEvent) => void | Promise<void>; type: string }>): void;
 
     parentDomNode: Node;
     execute: () => void;