refactor(note_create): simplify type implementation and documentation

This commit is contained in:
Jakob Schlanstedt 2025-10-28 18:03:32 +01:00
parent bcb29d22f5
commit a5ef5eee2f
12 changed files with 135 additions and 160 deletions

View File

@ -11,7 +11,7 @@ import froca from "../services/froca.js";
import linkService from "../services/link.js";
import { t } from "../services/i18n.js";
import { CreateChildrenResponse, SqlExecuteResponse } from "@triliumnext/commons";
import noteCreateService, { CreateNoteIntoInboxURLOpts, CreateNoteTarget } from "../services/note_create.js";
import noteCreateService, { CreateNoteIntoInboxOpts, CreateNoteTarget } from "../services/note_create.js";
export default class Entrypoints extends Component {
constructor() {
@ -26,7 +26,7 @@ export default class Entrypoints extends Component {
async createNoteIntoInboxCommand() {
await noteCreateService.createNote(
{ target: CreateNoteTarget.IntoInbox } as CreateNoteIntoInboxURLOpts
{ target: CreateNoteTarget.IntoInbox } as CreateNoteIntoInboxOpts
);
}

View File

@ -1,5 +1,5 @@
import appContext, { type EventData } from "./app_context.js";
import noteCreateService, { CreateNoteTarget, CreateNoteIntoURLOpts, CreateNoteAfterURLOpts } from "../services/note_create.js";
import noteCreateService, { CreateNoteTarget, CreateNoteIntoUrlOpts, CreateNoteAfterUrlOpts } from "../services/note_create.js";
import treeService from "../services/tree.js";
import hoistedNoteService from "../services/hoisted_note.js";
import Component from "./component.js";
@ -55,7 +55,7 @@ export default class MainTreeExecutors extends Component {
isProtected: activeNoteContext.note.isProtected,
saveSelection: false,
promptForType: false,
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
);
}
@ -84,7 +84,7 @@ export default class MainTreeExecutors extends Component {
targetBranchId: node.data.branchId,
isProtected: isProtected,
saveSelection: false
} as CreateNoteAfterURLOpts
} as CreateNoteAfterUrlOpts
);
}
}

View File

@ -8,7 +8,7 @@ import options from "../services/options.js";
import froca from "../services/froca.js";
import utils from "../services/utils.js";
import toastService from "../services/toast.js";
import noteCreateService, { CreateNoteIntoURLOpts, CreateNoteTarget } from "../services/note_create.js";
import noteCreateService, { CreateNoteIntoUrlOpts, CreateNoteTarget } from "../services/note_create.js";
export default class RootCommandExecutor extends Component {
editReadOnlyNoteCommand() {
@ -249,7 +249,7 @@ export default class RootCommandExecutor extends Component {
messages: [],
title: "New AI Chat"
}),
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
);
if (!result.note) {

View File

@ -2,7 +2,7 @@ import NoteColorPicker from "./custom-items/NoteColorPicker.jsx";
import treeService from "../services/tree.js";
import froca from "../services/froca.js";
import clipboard from "../services/clipboard.js";
import noteCreateService, { CreateNoteAfterURLOpts, CreateNoteIntoURLOpts, CreateNoteTarget } from "../services/note_create.js";
import noteCreateService, { CreateNoteAfterUrlOpts, CreateNoteIntoUrlOpts, CreateNoteTarget } from "../services/note_create.js";
import contextMenu, { type MenuCommandItem, type MenuItem } from "./context_menu.js";
import appContext, { type ContextMenuCommandData, type FilteredCommandNames } from "../components/app_context.js";
import noteTypesService from "../services/note_types.js";
@ -293,7 +293,7 @@ export default class TreeContextMenu implements SelectMenuItemEventListener<Tree
isProtected: isProtected,
templateNoteId: templateNoteId,
promptForType: false,
} as CreateNoteAfterURLOpts
} as CreateNoteAfterUrlOpts
);
} else if (command === "insertChildNote") {
const parentNotePath = treeService.getNotePath(this.node);
@ -306,7 +306,7 @@ export default class TreeContextMenu implements SelectMenuItemEventListener<Tree
isProtected: this.node.data.isProtected,
templateNoteId: templateNoteId,
promptForType: false,
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
);
} else if (command === "openNoteInSplit") {
const subContexts = appContext.tabManager.getActiveContext()?.getSubContexts();

View File

@ -1,6 +1,6 @@
import server from "./server.js";
import appContext from "../components/app_context.js";
import noteCreateService, { CreateNoteIntoURLOpts, CreateNoteTarget, CreateNoteIntoInboxURLOpts } from "./note_create.js";
import noteCreateService, { CreateNoteIntoUrlOpts, CreateNoteTarget, CreateNoteIntoInboxOpts } from "./note_create.js";
import froca from "./froca.js";
import { t } from "./i18n.js";
import commandRegistry from "./command_registry.js";
@ -487,7 +487,7 @@ function initNoteAutocomplete($el: JQuery<HTMLElement>, options?: Options) {
title: suggestion.noteTitle,
activate: true,
promptForType: true,
} as CreateNoteIntoInboxURLOpts
} as CreateNoteIntoInboxOpts
);
if (!note) return;
@ -507,7 +507,7 @@ function initNoteAutocomplete($el: JQuery<HTMLElement>, options?: Options) {
title: suggestion.noteTitle,
activate: false,
promptForType: true,
} as CreateNoteIntoInboxURLOpts,
} as CreateNoteIntoInboxOpts,
);
if (!note) return;
@ -528,7 +528,7 @@ function initNoteAutocomplete($el: JQuery<HTMLElement>, options?: Options) {
title: suggestion.noteTitle,
activate: true,
promptForType: true,
} as CreateNoteIntoURLOpts,
} as CreateNoteIntoUrlOpts,
);
if (!note) return;
@ -549,7 +549,7 @@ function initNoteAutocomplete($el: JQuery<HTMLElement>, options?: Options) {
title: suggestion.noteTitle,
activate: false,
promptForType: true,
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
);
if (!note) return;

View File

@ -13,44 +13,56 @@ import type { CKTextEditor } from "@triliumnext/ckeditor5";
import dateNoteService from "../services/date_notes.js";
/**
* The `note_create` function can be called with multiple valid combinations
* of arguments. This type hierarchy defines and enforces which combinations
* are valid at compile time.
* Defines the type hierarchy and rules for valid argument combinations
* accepted by `note_create`.
*
* The function overloads later in `note_create` correspond to these types,
* ensuring that each variant of note creation accepts only the correct
* set of arguments.
* ## Overview
* Each variant (e.g. `CreateNoteIntoUrlOpts`, `CreateNoteBeforeUrlOpts`, etc.)
* extends `CreateNoteOpts` and enforces specific constraints to ensure only
* valid note creation options are allowed at compile time.
*
* Theoretically: If type checking produces no errors, then the provided
* arguments represent a valid state assuming the types below are defined
* correctly. Through the CurryHoward correspondence, this type system
* effectively acts as a proof system: a successful type check serves as a
* compile-time proof that the arguments of `create_note` can only produce
* a valid state.
* ## Type Safety
* The `PromptingRule` ensures that `promptForType` and `type` stay mutually
* exclusive (if prompting, `type` is undefined).
*
* To align with its theoretical foundation in type theory (via the
* CurryHoward correspondence), `type` is used instead of `interface`
* The type system prevents invalid argument mixes by design successful type
* checks guarantee a valid state, following CurryHoward correspondence
* principles (types as proofs).
*
* * Hierarchy of general to specific categories(hypernyms -> hyponyms):
* ## Maintenance
* If adding or modifying `Opts`, ensure:
* - All valid combinations are represented (avoid *false negatives*).
* - No invalid ones slip through (avoid *false positives*).
*
* * CreateNoteEntity
* |
* \-- CreateNoteOpts
* |
* +-- CreateNoteAtUrlOpts
* | +-- CreateNoteIntoURLOpts
* | \-- CreateNoteSiblingURLOpts
* | +-- CreateNoteBeforeURLOpts
* | \-- CreateNoteAfterURLOpts
* |
* \-- CreateNoteIntoInboxURLOpts
* Hierarchy (general specific):
* - CreateNoteOpts
* - CreateNoteAtUrlOpts
* - CreateNoteIntoUrlOpts
* - CreateNoteBeforeUrlOpts
* - CreateNoteAfterUrlOpts
* - CreateNoteIntoInboxOpts
*/
/**
* this is the shared basis for all types. Every other type is child (hyponym)
* of it (Its the domain hypernym).
/** enforces a truth rule:
* - If `promptForType` is true `type` must be undefined.
* - If `promptForType` is false `type` must be defined.
*/
type CreateNoteEntity = {
type PromptingRule = {
promptForType: true;
type?: never;
} | {
promptForType?: false;
type: string;
};
/**
* Base type for all note creation options (domain hypernym).
* All specific note option types extend from this.
*
* Combine with `&` to ensure valid logical combinations.
*/
export type CreateNoteOpts = {
target: CreateNoteTarget;
isProtected?: boolean;
saveSelection?: boolean;
@ -62,43 +74,30 @@ type CreateNoteEntity = {
activate?: boolean;
focus?: "title" | "content";
textEditor?: CKTextEditor;
}
export type CreateNoteOpts =
| (CreateNoteEntity & {
promptForType: true;
type?: never;
})
| (CreateNoteEntity & {
promptForType?: false;
type?: string;
});
} & PromptingRule;
/*
* For creating a note in a specific path. At is the broader category (hypernym)
* of "into" and "as siblings". It is not exported because it only exists, to
* have its legal values propagated to its children (types inheriting from it).
* Defines options for creating a note at a specific path.
* Serves as a base (not exported) for "into", "before", and "after" variants,
* sharing common URL-related fields.
*/
type CreateNoteAtUrlOpts = CreateNoteOpts & {
// `Url` means either parentNotePath or parentNoteId.
// The vocabulary is inspired by its loose semantics of getNoteIdFromUrl.
// `Url` may refer to either parentNotePath or parentNoteId.
// The vocabulary is inspired by existing function getNoteIdFromUrl.
parentNoteUrl: string;
/*
* targetBranchId disambiguates the position for cloned notes. This is a
* concern whenever we are given a note URL.
*/
// Disambiguates the position for cloned notes.
targetBranchId: string;
}
export type CreateNoteIntoURLOpts = CreateNoteAtUrlOpts;
export type CreateNoteIntoUrlOpts = CreateNoteAtUrlOpts;
export type CreateNoteBeforeUrlOpts = CreateNoteAtUrlOpts;
export type CreateNoteAfterUrlOpts = CreateNoteAtUrlOpts;
type CreateNoteSiblingURLOpts = CreateNoteAtUrlOpts;
export type CreateNoteBeforeURLOpts = CreateNoteSiblingURLOpts;
export type CreateNoteAfterURLOpts = CreateNoteSiblingURLOpts;
export type CreateNoteIntoInboxURLOpts = CreateNoteOpts & {
type NeverDefineParentNoteUrlRule = {
parentNoteUrl?: never;
}
};
export type CreateNoteIntoInboxOpts = CreateNoteOpts & NeverDefineParentNoteUrlRule;
export enum CreateNoteTarget {
IntoNoteURL,
@ -118,23 +117,6 @@ interface DuplicateResponse {
note: FNote;
}
/* We are overloading createNote for each type */
async function createNote(
options: CreateNoteIntoURLOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }>;
async function createNote(
options: CreateNoteAfterURLOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }>;
async function createNote(
options: CreateNoteBeforeURLOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }>;
async function createNote(
options: CreateNoteIntoInboxURLOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }>;
async function createNote(
options: CreateNoteOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }> {
@ -143,41 +125,28 @@ async function createNote(
// handle prompts centrally to write once fix for all
if (options.promptForType) {
const { success, noteType, templateNoteId, notePath } = await chooseNoteType();
if (!success) return {
let maybeResolvedOptions = await promptForType(options);
if (!maybeResolvedOptions) {
return {
note: null, branch: undefined
};
resolvedOptions = {
...resolvedOptions,
promptForType: false,
type: noteType,
templateNoteId,
} as CreateNoteOpts;
if (notePath) {
resolvedOptions = resolvedOptions as CreateNoteIntoURLOpts;
resolvedOptions = {
...resolvedOptions,
target: CreateNoteTarget.IntoNoteURL,
parentNoteUrl: notePath,
} as CreateNoteIntoURLOpts;
}
resolvedOptions = maybeResolvedOptions;
}
switch (resolvedOptions.target) {
case CreateNoteTarget.IntoNoteURL:
return await createNoteIntoNote(resolvedOptions as CreateNoteIntoURLOpts);
return await createNoteAtNote("into", {...options} as CreateNoteAtUrlOpts);
case CreateNoteTarget.BeforeNoteURL:
return await createNoteBeforeNote(resolvedOptions as CreateNoteBeforeURLOpts);
return await createNoteAtNote("before", resolvedOptions as CreateNoteBeforeUrlOpts);
case CreateNoteTarget.AfterNoteURL:
return await createNoteAfterNote(resolvedOptions as CreateNoteAfterURLOpts);
return await createNoteAtNote("after", resolvedOptions as CreateNoteAfterUrlOpts);
case CreateNoteTarget.IntoInbox:
return await createNoteIntoInbox(resolvedOptions as CreateNoteIntoInboxURLOpts);
return await createNoteIntoInbox(resolvedOptions as CreateNoteIntoInboxOpts);
default: {
console.warn("[createNote] Unknown target:", options.target, resolvedOptions);
@ -187,14 +156,40 @@ async function createNote(
}
}
async function promptForType(
options: CreateNoteOpts
) : Promise<CreateNoteOpts | null> {
const { success, noteType, templateNoteId, notePath } = await chooseNoteType();
if (!success) {
return null;
}
let resolvedOptions = {
...options,
promptForType: false,
type: noteType,
templateNoteId,
} as CreateNoteOpts;
if (notePath) {
resolvedOptions = resolvedOptions as CreateNoteIntoUrlOpts;
resolvedOptions = {
...resolvedOptions,
target: CreateNoteTarget.IntoNoteURL,
parentNoteUrl: notePath,
} as CreateNoteIntoUrlOpts;
}
return resolvedOptions;
}
/**
* Core function that creates a new note under the specified parent note path.
* Creates a new note under a specified parent note path.
*
* @param target - Duplicates apps/server/src/routes/api/notes.ts createNote
* @param {CreateNoteEntity} [options] - Options controlling note creation (title, content, type, template, focus, etc.).
* with parentNotePath - The parent note path where the new note will be created.
* @returns {Promise<{ note: FNote | null; branch: FBranch | undefined }>}
* Resolves with the created note and branch entities.
* @param target - Mirrors the `createNote` API in apps/server/src/routes/api/notes.ts.
* @param options - Note creation options
* @returns A promise resolving with the created note and its branch.
*/
async function createNoteAtNote(
target: "into" | "after" | "before",
@ -271,35 +266,15 @@ async function createNoteAtNote(
}
// Small wrapper functions for @see createNoteAtNote, using it a certain way to
// remove code duplication
async function createNoteIntoNote(
options: CreateNoteIntoURLOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }> {
return createNoteAtNote("into", {...options} as CreateNoteAtUrlOpts);
}
async function createNoteBeforeNote(
options: CreateNoteBeforeURLOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }> {
return createNoteAtNote("before", {...options} as CreateNoteAtUrlOpts);
}
async function createNoteAfterNote(
options: CreateNoteAfterURLOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }> {
return createNoteAtNote("after", {...options} as CreateNoteAtUrlOpts);
}
/**
* Creates a new note inside the user's Inbox.
*
* @param {CreateNoteEntity} [options] - Optional settings such as title, type, template, or content.
* @param {CreateNoteIntoInboxOpts} [options] - Optional settings such as title, type, template, or content.
* @returns {Promise<{ note: FNote | null; branch: FBranch | undefined }>}
* Resolves with the created note and its branch, or `{ note: null, branch: undefined }` if the inbox is missing.
*/
async function createNoteIntoInbox(
options: CreateNoteIntoInboxURLOpts
options: CreateNoteIntoInboxOpts
): Promise<{ note: FNote | null; branch: FBranch | undefined }> {
const inboxNote = await dateNoteService.getInboxNote();
if (!inboxNote) {
@ -313,11 +288,11 @@ async function createNoteIntoInbox(
inboxNote.isProtected && protectedSessionHolder.isProtectedSessionAvailable();
}
const result = await createNoteIntoNote(
const result = await createNoteAtNote("into",
{
...options,
parentNoteUrl: inboxNote.noteId,
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
);
return result;

View File

@ -7,7 +7,7 @@ import branches from "../../../services/branches";
import { executeBulkActions } from "../../../services/bulk_action";
import froca from "../../../services/froca";
import { t } from "../../../services/i18n";
import note_create, { CreateNoteIntoURLOpts, CreateNoteTarget } from "../../../services/note_create.js";
import note_create, { CreateNoteIntoUrlOpts, CreateNoteTarget } from "../../../services/note_create.js";
import server from "../../../services/server";
import { ColumnMap } from "./data";
@ -44,7 +44,7 @@ export default class BoardApi {
parentNoteUrl: parentNotePath,
activate: false,
title,
} as CreateNoteIntoURLOpts);
} as CreateNoteIntoUrlOpts);
if (newNote && newBranch) {
await this.changeColumn(newNote.noteId, column);
@ -150,7 +150,7 @@ export default class BoardApi {
activate: false,
targetBranchId: relativeToBranchId,
title: t("board_view.new-item"),
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
);
if (!note || !branch) {

View File

@ -9,7 +9,7 @@ import branches from "../../../services/branches.js";
import Component from "../../../components/component.js";
import NoteColorPicker from "../../../menus/custom-items/NoteColorPicker.jsx";
import { RefObject } from "preact";
import { CreateNoteAfterURLOpts, CreateNoteBeforeURLOpts, CreateNoteTarget } from "../../../services/note_create.js";
import { CreateNoteAfterUrlOpts, CreateNoteBeforeUrlOpts, CreateNoteTarget } from "../../../services/note_create.js";
export function useContextMenu(parentNote: FNote, parentComponent: Component | null | undefined, tabulator: RefObject<Tabulator>): Partial<EventCallBackMethods> {
const events: Partial<EventCallBackMethods> = {};
@ -186,7 +186,7 @@ export function showRowContextMenu(parentComponent: Component, e: MouseEvent, ro
customOpts: {
target: CreateNoteTarget.BeforeNoteURL,
targetBranchId: rowData.branchId,
} as CreateNoteBeforeURLOpts
} as CreateNoteBeforeUrlOpts
})
},
{
@ -200,7 +200,7 @@ export function showRowContextMenu(parentComponent: Component, e: MouseEvent, ro
customOpts: {
target: CreateNoteTarget.AfterNoteURL,
targetBranchId: branchId,
} as CreateNoteAfterURLOpts
} as CreateNoteAfterUrlOpts
});
}
},
@ -213,7 +213,7 @@ export function showRowContextMenu(parentComponent: Component, e: MouseEvent, ro
customOpts: {
target: CreateNoteTarget.AfterNoteURL,
targetBranchId: rowData.branchId,
} as CreateNoteAfterURLOpts
} as CreateNoteAfterUrlOpts
})
},
{ kind: "separator" },

View File

@ -1,6 +1,6 @@
import { EventCallBackMethods, RowComponent, Tabulator } from "tabulator-tables";
import { CommandListenerData } from "../../../components/app_context";
import note_create, { CreateNoteOpts, CreateNoteIntoURLOpts as CreateNoteIntoURLOpts, CreateNoteTarget } from "../../../services/note_create";
import note_create, { CreateNoteOpts, CreateNoteIntoUrlOpts as CreateNoteIntoUrlOpts, CreateNoteTarget } from "../../../services/note_create";
import { useLegacyImperativeHandlers } from "../../react/hooks";
import { RefObject } from "preact";
import { setAttribute, setLabel } from "../../../services/attributes";
@ -23,7 +23,7 @@ export default function useRowTableEditing(api: RefObject<Tabulator>, attributeD
{
parentNoteUrl: notePath,
...opts
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
).then(({ branch }) => {
if (branch) {
setTimeout(() => {

View File

@ -3,7 +3,7 @@ import appContext from "../../components/app_context";
import contextMenu from "../../menus/context_menu";
import branches from "../../services/branches";
import { t } from "../../services/i18n";
import note_create, { CreateNoteIntoURLOpts, CreateNoteTarget } from "../../services/note_create";
import note_create, { CreateNoteIntoUrlOpts, CreateNoteTarget } from "../../services/note_create";
import tree from "../../services/tree";
import ActionButton from "../react/ActionButton";
import { ParentComponent } from "../react/react_utils";
@ -33,7 +33,7 @@ export default function MobileDetailMenu() {
{
target: CreateNoteTarget.IntoNoteURL,
parentNoteUrl: appContext.tabManager.getActiveContextNotePath() ?? undefined
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
);
} else if (command === "delete") {
const notePath = appContext.tabManager.getActiveContextNotePath();

View File

@ -7,7 +7,7 @@ import branchService from "../services/branches.js";
import ws from "../services/ws.js";
import NoteContextAwareWidget from "./note_context_aware_widget.js";
import server from "../services/server.js";
import noteCreateService, { CreateNoteIntoURLOpts, CreateNoteTarget } from "../services/note_create.js";
import noteCreateService, { CreateNoteIntoUrlOpts, CreateNoteTarget } from "../services/note_create.js";
import toastService from "../services/toast.js";
import appContext, { type CommandListenerData, type EventData } from "../components/app_context.js";
import keyboardActionsService from "../services/keyboard_actions.js";
@ -229,7 +229,7 @@ export default class NoteTreeWidget extends NoteContextAwareWidget {
target: CreateNoteTarget.IntoNoteURL,
parentNoteUrl: parentNotePath,
isProtected: node.data.isProtected
} as CreateNoteIntoURLOpts,
} as CreateNoteIntoUrlOpts,
);
} else if (target.classList.contains("enter-workspace-button")) {
const node = $.ui.fancytree.getNode(e as unknown as Event);
@ -1847,7 +1847,7 @@ export default class NoteTreeWidget extends NoteContextAwareWidget {
target: CreateNoteTarget.IntoNoteURL,
parentNoteUrl: notePath,
isProtected: node.data.isProtected
} as CreateNoteIntoURLOpts
} as CreateNoteIntoUrlOpts
)
}
}),

View File

@ -19,7 +19,7 @@ import contextMenu from "../../../menus/context_menu";
import type { CommandData, FilteredCommandNames } from "../../../components/app_context";
import { AttributeType } from "@triliumnext/commons";
import attributes from "../../../services/attributes";
import note_create, { CreateNoteAfterURLOpts, CreateNoteIntoURLOpts, CreateNoteTarget, CreateNoteIntoInboxURLOpts } from "../../../services/note_create";
import note_create, { CreateNoteAfterUrlOpts, CreateNoteIntoUrlOpts, CreateNoteTarget, CreateNoteIntoInboxOpts } from "../../../services/note_create";
import { CreateNoteAction } from "@triliumnext/commons";
type AttributeCommandNames = FilteredCommandNames<CommandData>;
@ -266,7 +266,7 @@ export default function AttributeEditor({ api, note, componentId, notePath, ntxI
target: CreateNoteTarget.IntoInbox,
title,
activate: false
} as CreateNoteIntoInboxURLOpts
} as CreateNoteIntoInboxOpts
);
return note?.getBestNotePathString() ?? "";
}
@ -280,7 +280,7 @@ export default function AttributeEditor({ api, note, componentId, notePath, ntxI
title,
activate: false,
promptForType: true,
} as CreateNoteIntoURLOpts,
} as CreateNoteIntoUrlOpts,
)
return resp?.note?.getBestNotePathString() ?? "";
}