Add support to specify the type returned by query functions (#137)

* Add generics to indexable getters

Add generic for indexable getters (query functions, as well as `currentFile` and similar) to specify the return type.

* Add types for specifically defined fields

Add utility types, accessible in [className].Typed, that allows for field-related functions to give narrower results, if the user knows a file/section/etc. has specific fields.

Author: Gudine

datacore.api.md

@@ -149,6 +149,17 @@ export class Canvas implements Linkable, File_2, Linkbearing, Taggable, Indexabl
     static TYPES: string[];
 }
 
+// @public (undocumented)
+export namespace Canvas {
+    // Warning: (ae-forgotten-export) The symbol "TypedFieldbearing" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<Canvas, keyof TypedFieldbearing<Fields>>, TypedFieldbearing<Fields> {
+    }
+}
+
 // @public
 export type CanvasCard = CanvasTextCard | CanvasFileCard | CanvasWebCard;
 
@@ -218,6 +229,15 @@ export class CanvasTextCard extends BaseCanvasCard implements Linkbearing, Tagga
     static TYPES: string[];
 }
 
+// @public (undocumented)
+export namespace CanvasTextCard {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<CanvasTextCard, keyof TypedFieldbearing<Fields>>, TypedFieldbearing<Fields> {
+    }
+}
+
 // @public (undocumented)
 export class CanvasWebCard extends BaseCanvasCard implements Indexable {
     // (undocumented)
@@ -396,21 +416,21 @@ export class DatacoreApi {
     executeTs(source: string, container: HTMLElement, component: Component | MarkdownPostProcessorContext, sourcePath: string): MarkdownRenderChild;
     executeTsx(source: string, container: HTMLElement, component: Component | MarkdownPostProcessorContext, sourcePath: string): MarkdownRenderChild;
     fileLink(path: string): Link;
-    fullquery(query: string | IndexQuery): SearchResult<Indexable>;
+    fullquery<T extends Indexable = Indexable>(query: string | IndexQuery): SearchResult<T>;
     headerLink(path: string, header: string): Link;
     local(path: string): DatacoreLocalApi;
     get luxon(): typeof luxon_2;
-    page(path: string | Link): MarkdownPage | undefined;
+    page<T extends MarkdownPage = MarkdownPage>(path: string | Link): T | undefined;
     parseLink(linktext: string): Link;
     parseQuery(query: string | IndexQuery): IndexQuery;
     get preact(): typeof preact_2;
-    query(query: string | IndexQuery): Indexable[];
+    query<T extends Indexable = Indexable>(query: string | IndexQuery): T[];
     resolvePath(path: string | Link, sourcePath?: string): string;
     tryEvaluate(expression: string | Expression, variables?: Record<string, Literal>, sourcePath?: string): Result<Literal, string>;
-    tryFullQuery(query: string | IndexQuery): Result<SearchResult<Indexable>, string>;
+    tryFullQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<SearchResult<T>, string>;
     tryParseLink(linktext: string): Result<Link, string>;
     tryParseQuery(query: string | IndexQuery): Result<IndexQuery, string>;
-    tryQuery(query: string | IndexQuery): Result<Indexable[], string>;
+    tryQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<T[], string>;
 }
 
 // @public
@@ -431,12 +451,12 @@ export class DatacoreLocalApi {
     coerce: typeof Coerce;
     get core(): Datacore;
     createContext: typeof preact_2.createContext;
-    currentFile(): MarkdownPage;
+    currentFile<T extends MarkdownPage = MarkdownPage>(): T;
     currentPath(): string;
     embed: any;
     evaluate(expression: string | Expression, variables?: Record<string, Literal>, sourcePath?: string): Literal;
     fileLink(path: string): Link;
-    fullquery(query: string | IndexQuery): SearchResult<Indexable>;
+    fullquery<T extends Indexable = Indexable>(query: string | IndexQuery): SearchResult<T>;
     Group: typeof Group;
     headerLink(path: string, header: string): Link;
     Icon: typeof Icon;
@@ -454,7 +474,7 @@ export class DatacoreLocalApi {
     // (undocumented)
     path: string;
     get preact(): typeof preact_2;
-    query(query: string | IndexQuery): Indexable[];
+    query<T extends Indexable = Indexable>(query: string | IndexQuery): T[];
     require(path: string | Link): Promise<unknown>;
     resolvePath(path: string | Link, sourcePath?: string): string;
     // (undocumented)
@@ -467,35 +487,35 @@ export class DatacoreLocalApi {
     // (undocumented)
     Textbox: typeof Textbox;
     tryEvaluate(expression: string | Expression, variables?: Record<string, Literal>, sourcePath?: string): Result<Literal, string>;
-    tryFullQuery(query: string | IndexQuery): Result<SearchResult<Indexable>, string>;
+    tryFullQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<SearchResult<T>, string>;
     tryParseLink(linktext: string): Result<Link, string>;
     tryParseQuery(query: string | IndexQuery): Result<IndexQuery, string>;
-    tryQuery(query: string | IndexQuery): Result<Indexable[], string>;
+    tryQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<T[], string>;
     useArray<T, U>(input: T[] | DataArray<T>, process: (data: DataArray<T>) => DataArray<U>, deps?: unknown[]): U[];
     useCallback: typeof hooks.useCallback;
     useContext: typeof hooks.useContext;
-    useCurrentFile(settings?: {
+    useCurrentFile<T extends MarkdownPage = MarkdownPage>(settings?: {
         debounce?: number;
-    }): MarkdownPage;
+    }): T;
     useCurrentPath(settings?: {
         debounce?: number;
     }): string;
     useEffect: typeof hooks.useEffect;
-    useFile(path: string, settings?: {
+    useFile<T extends Indexable = Indexable>(path: string, settings?: {
         debounce?: number;
-    }): Indexable | undefined;
-    useFullQuery(query: string | IndexQuery, settings?: {
+    }): T | undefined;
+    useFullQuery<T extends Indexable = Indexable>(query: string | IndexQuery, settings?: {
         debounce?: number;
-    }): SearchResult<Indexable>;
+    }): SearchResult<T>;
     useIndexUpdates(settings?: {
         debounce?: number;
     }): number;
     // Warning: (ae-forgotten-export) The symbol "useInterning" needs to be exported by the entry point index.d.ts
     useInterning: typeof useInterning;
     useMemo: typeof hooks.useMemo;
-    useQuery(query: string | IndexQuery, settings?: {
+    useQuery<T extends Indexable = Indexable>(query: string | IndexQuery, settings?: {
         debounce?: number;
-    }): Indexable[];
+    }): T[];
     useReducer: typeof hooks.useReducer;
     useRef: typeof hooks.useRef;
     useState: typeof hooks.useState;
@@ -1133,6 +1153,17 @@ export class MarkdownBlock implements Indexable, Linkbearing, Taggable, Fieldbea
     value(key: string): Literal | undefined;
 }
 
+// @public (undocumented)
+export namespace MarkdownBlock {
+    // Warning: (ae-forgotten-export) The symbol "TypedValuebearing" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownBlock, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export class MarkdownCodeblock extends MarkdownBlock implements Indexable, Fieldbearing, Linkbearing {
     // (undocumented)
@@ -1164,6 +1195,15 @@ export class MarkdownCodeblock extends MarkdownBlock implements Indexable, Field
     value(key: string): Literal | undefined;
 }
 
+// @public (undocumented)
+export namespace MarkdownCodeblock {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownCodeblock, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export class MarkdownDatablock extends MarkdownBlock implements Indexable, Fieldbearing, Linkbearing {
     // (undocumented)
@@ -1189,6 +1229,15 @@ export class MarkdownDatablock extends MarkdownBlock implements Indexable, Field
     value(key: string): Literal | undefined;
 }
 
+// @public (undocumented)
+export namespace MarkdownDatablock {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownDatablock, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export class MarkdownListBlock extends MarkdownBlock implements Taggable, Linkbearing {
     $elements: MarkdownListItem[];
@@ -1207,6 +1256,15 @@ export class MarkdownListBlock extends MarkdownBlock implements Taggable, Linkbe
     static TYPES: string[];
 }
 
+// @public (undocumented)
+export namespace MarkdownListBlock {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownListBlock, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export class MarkdownListItem implements Indexable, Linkbearing, Taggable, Fieldbearing {
     $blockId?: string;
@@ -1246,6 +1304,15 @@ export class MarkdownListItem implements Indexable, Linkbearing, Taggable, Field
     value(key: string): Literal | undefined;
 }
 
+// @public (undocumented)
+export namespace MarkdownListItem {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownListItem, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export class MarkdownPage implements File_2, Linkbearing, Taggable, Indexable, Fieldbearing {
     $ctime: DateTime;
@@ -1282,6 +1349,15 @@ export class MarkdownPage implements File_2, Linkbearing, Taggable, Indexable, F
     value(key: string): Literal | undefined;
 }
 
+// @public (undocumented)
+export namespace MarkdownPage {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownPage, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export class MarkdownSection implements Indexable, Taggable, Linkable, Linkbearing, Fieldbearing {
     $blocks: MarkdownBlock[];
@@ -1316,6 +1392,15 @@ export class MarkdownSection implements Indexable, Taggable, Linkable, Linkbeari
     value(key: string): Literal | undefined;
 }
 
+// @public (undocumented)
+export namespace MarkdownSection {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownSection, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export class MarkdownTaskItem extends MarkdownListItem implements Indexable, Linkbearing, Taggable, Fieldbearing {
     get $completed(): boolean;
@@ -1335,6 +1420,15 @@ export class MarkdownTaskItem extends MarkdownListItem implements Indexable, Lin
     static TYPES: string[];
 }
 
+// @public (undocumented)
+export namespace MarkdownTaskItem {
+    // (undocumented)
+    export interface Typed<Fields extends {
+        [key in string]?: Literal;
+    }> extends Omit<MarkdownTaskItem, keyof TypedValuebearing<Fields>>, TypedValuebearing<Fields> {
+    }
+}
+
 // @public
 export interface MethodExpression {
     arguments: Expression[];

src/api/api.ts

@@ -57,28 +57,33 @@ export class DatacoreApi {
     /////////////////////////
 
     /** Load a markdown file by full path or link. */
+    public page<T extends MarkdownPage = MarkdownPage>(path: string | Link): T | undefined;
     public page(path: string | Link): MarkdownPage | undefined {
         const realPath = path instanceof Link ? path.path : path;
 
         return this.core.datastore.load(realPath) as MarkdownPage | undefined;
     }
 
     /** Execute a textual or typed index query, returning all results. */
+    public query<T extends Indexable = Indexable>(query: string | IndexQuery): T[];
     public query(query: string | IndexQuery): Indexable[] {
         return this.tryQuery(query).orElseThrow();
     }
 
     /** Execute a textual or typed index query, returning all results. */
+    public tryQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<T[], string>;
     public tryQuery(query: string | IndexQuery): Result<Indexable[], string> {
         return this.tryFullQuery(query).map((result) => result.results);
     }
 
     /** Execute a textual or typed index query, returning results plus performance metadata. */
+    public fullquery<T extends Indexable = Indexable>(query: string | IndexQuery): SearchResult<T>;
     public fullquery(query: string | IndexQuery): SearchResult<Indexable> {
         return this.tryFullQuery(query).orElseThrow();
     }
 
     /** Execute a textual or typed index query, returning results plus performance metadata. */
+    public tryFullQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<SearchResult<T>, string>;
     public tryFullQuery(query: string | IndexQuery): Result<SearchResult<Indexable>, string> {
         const parsedQuery = typeof query === "string" ? QUERY.query.tryParse(query) : query;
         return this.core.datastore.search(parsedQuery);

src/api/local-api.tsx

@@ -47,6 +47,7 @@ export class DatacoreLocalApi {
     }
 
     /** The full markdown file metadata for the current file. */
+    public currentFile<T extends MarkdownPage = MarkdownPage>(): T;
     public currentFile(): MarkdownPage {
         return this.api.page(this.path)!;
     }
@@ -167,21 +168,25 @@ export class DatacoreLocalApi {
     }
 
     /** Execute a textual or typed index query, returning all results. */
+    public query<T extends Indexable = Indexable>(query: string | IndexQuery): T[];
     public query(query: string | IndexQuery): Indexable[] {
         return this.api.query(query);
     }
 
     /** Execute a textual or typed index query, returning all results. */
+    public tryQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<T[], string>;
     public tryQuery(query: string | IndexQuery): Result<Indexable[], string> {
         return this.api.tryQuery(query);
     }
 
     /** Execute a textual or typed index query, returning results plus performance metadata. */
+    public fullquery<T extends Indexable = Indexable>(query: string | IndexQuery): SearchResult<T>;
     public fullquery(query: string | IndexQuery): SearchResult<Indexable> {
         return this.api.fullquery(query);
     }
 
     /** Execute a textual or typed index query, returning results plus performance metadata. */
+    public tryFullQuery<T extends Indexable = Indexable>(query: string | IndexQuery): Result<SearchResult<T>, string>;
     public tryFullQuery(query: string | IndexQuery): Result<SearchResult<Indexable>, string> {
         return this.api.tryFullQuery(query);
     }
@@ -225,6 +230,7 @@ export class DatacoreLocalApi {
     }
 
     /** Use the file metadata for the current file. Automatically updates the view when the current file metadata changes. */
+    public useCurrentFile<T extends MarkdownPage = MarkdownPage>(settings?: { debounce?: number }): T;
     public useCurrentFile(settings?: { debounce?: number }): MarkdownPage {
         return useFileMetadata(this.core, this.path, settings) as MarkdownPage;
     }
@@ -235,6 +241,7 @@ export class DatacoreLocalApi {
     }
 
     /** Use the file metadata for a specific file. Automatically updates the view when the file changes. */
+    public useFile<T extends Indexable = Indexable>(path: string, settings?: { debounce?: number }): T | undefined;
     public useFile(path: string, settings?: { debounce?: number }): Indexable | undefined {
         return useFileMetadata(this.core, path, settings);
     }
@@ -248,11 +255,16 @@ export class DatacoreLocalApi {
      * Run a query, automatically re-running it whenever the vault changes. Returns more information about the query
      * execution, such as index revision and total search duration.
      */
+    public useFullQuery<T extends Indexable = Indexable>(
+        query: string | IndexQuery,
+        settings?: { debounce?: number }
+    ): SearchResult<T>;
     public useFullQuery(query: string | IndexQuery, settings?: { debounce?: number }): SearchResult<Indexable> {
         return useFullQuery(this.core, this.parseQuery(query), settings);
     }
 
     /** Run a query, automatically re-running it whenever the vault changes. */
+    public useQuery<T extends Indexable = Indexable>(query: string | IndexQuery, settings?: { debounce?: number }): T[];
     public useQuery(query: string | IndexQuery, settings?: { debounce?: number }): Indexable[] {
         // Hooks need to be called in a consistent order, so we don't nest the `useQuery` call in the DataArray.wrap _just_ in case.
         return useQuery(this.core, this.parseQuery(query), settings);

src/index/types/canvas.ts

@@ -26,6 +26,8 @@ import {
 import { InlineField, jsonInlineField, valueInlineField } from "index/import/inline-field";
 import { File } from "index/types/indexable";
 import { mapObjectValues } from "utils/data";
+import { Literal } from "expression/literal";
+import { TypedFieldbearing } from "./typed-field";
 
 /** A canvas file, consisting of a set of canvas cards. */
 export class Canvas implements Linkable, File, Linkbearing, Taggable, Indexable, Fieldbearing {
@@ -123,6 +125,13 @@ export class Canvas implements Linkable, File, Linkbearing, Taggable, Indexable,
     );
 }
 
+/** @public */
+export namespace Canvas {
+    export interface Typed<Fields extends { [key in string]?: Literal }>
+        extends Omit<Canvas, keyof TypedFieldbearing<Fields>>,
+            TypedFieldbearing<Fields> {}
+}
+
 /** All supported canvas card types. */
 export type CanvasCard = CanvasTextCard | CanvasFileCard | CanvasWebCard;
 
@@ -233,6 +242,13 @@ export class CanvasTextCard extends BaseCanvasCard implements Linkbearing, Tagga
     );
 }
 
+/** @public */
+export namespace CanvasTextCard {
+    export interface Typed<Fields extends { [key in string]?: Literal }>
+        extends Omit<CanvasTextCard, keyof TypedFieldbearing<Fields>>,
+            TypedFieldbearing<Fields> {}
+}
+
 /** Canvas card that is just a file embedding. */
 export class CanvasFileCard extends BaseCanvasCard implements Indexable {
     static TYPES = ["canvas-card", "markdown", "canvas-file-card", TAGGABLE_TYPE, LINKABLE_TYPE, FIELDBEARING_TYPE];