tw5-typed 0.2.0 → 0.2.1

package/package.json

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

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,17 +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
      */
-    addTiddlers: (tiddler: Array<Tiddler | ITiddlerFields>) => void;
+    addTiddlers: (tiddler: Array<Tiddler | 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).

package/src/server.d.ts

@@ -13,14 +13,91 @@ declare module 'tiddlywiki' {
     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, any>> = (
+  export type ServerEndpointHandler<T = Record<string, unknown>> = (
     request: Http.ClientRequest,
     response: Http.ServerResponse,
     context: ServerEndpointContext & T,

package/src/utils.d.ts

@@ -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;
     /**

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;