Merge branch 'refactor/v1'

Injector/Parser.ts

@@ -2,6 +2,9 @@ import { isSortingOption, sortingOptions } from "./Query";
 import type { Query } from "./Query";
 import YAML from "yaml";
 
+/**
+ * Custom error class for parsing errors
+ */
 export class ParsingError extends Error {
   inner: Error | undefined;
 
@@ -19,6 +22,12 @@ export class ParsingError extends Error {
   }
 }
 
+/**
+ * Parses a raw string into a Query object
+ * @param raw - the raw string to parse
+ * @returns the parsed Query object
+ * @throws ParsingError if the raw string cannot be parsed
+ */
 export function parseQuery(raw: string): Query {
   let obj: any;
 
@@ -35,6 +44,12 @@ export function parseQuery(raw: string): Query {
   return parseObject(obj);
 }
 
+/**
+ * Attempts to parse a raw string as JSON
+ * @param raw - the raw string to parse
+ * @returns the parsed JSON object
+ * @throws ParsingError if the raw string is not valid JSON
+ */
 function tryParseAsJson(raw: string): any {
   try {
     return JSON.parse(raw);
@@ -43,6 +58,12 @@ function tryParseAsJson(raw: string): any {
   }
 }
 
+/**
+ * Attempts to parse a raw string as YAML
+ * @param raw - the raw string to parse
+ * @returns the parsed YAML object
+ * @throws ParsingError if the raw string is not valid YAML
+ */
 function tryParseAsYaml(raw: string): any {
   try {
     return YAML.parse(raw);
@@ -51,6 +72,12 @@ function tryParseAsYaml(raw: string): any {
   }
 }
 
+/**
+ * Parses a generic object into a Query object
+ * @param query - the object to parse
+ * @returns the parsed Query object
+ * @throws ParsingError if the object is not a valid Query object
+ */
 function parseObject(query: any): Query {
   if (query.hasOwnProperty("name") && typeof query.name !== "string") {
     throw new ParsingError("'name' field must be a string");
@@ -107,6 +134,10 @@ function parseObject(query: any): Query {
   return query as Query;
 }
 
+/**
+ * Formats the sorting options as a string
+ * @returns the formatted string of sorting options
+ */
 function formatSortingOpts(): string {
   return sortingOptions.map((e) => `'${e}'`).join(", ");
-}
+}

Injector/Query.ts

@@ -1,17 +1,31 @@
+/**
+ * An array of available sorting options.
+ */
 export const sortingOptions = [
   "date",
   "dateDESC",
   "priority",
   "priorityDESC",
 ];
 
+/**
+ * A type representing a sorting option.
+ */
 export type SortingOption = typeof sortingOptions[number];
 
+/**
+ * A type guard to check if a value is a valid sorting option.
+ * @param value The value to check.
+ * @returns True if the value is a valid sorting option, false otherwise.
+ */
 export function isSortingOption(value: string): value is SortingOption;
 export function isSortingOption(value: any) {
   return sortingOptions.includes(value);
 }
 
+/**
+ * An interface representing a query.
+ */
 export type Query = {
   name?: string
   timeMin?: string;
@@ -20,4 +34,4 @@ export type Query = {
   filter?: string;
   sorting?: SortingOption[];
   group?: boolean;
-};
+};

Injector/QueryInjector.ts

@@ -1,24 +1,23 @@
 import {
-  App,
-  MarkdownPostProcessorContext,
+  type MarkdownPostProcessorContext,
   MarkdownRenderChild,
 } from "obsidian";
+import type { SvelteComponentDev } from "svelte/internal";
 
 import type SyncCalendarPlugin from "main";
-import type GoogleCalendarSync from "../Syncs/GoogleCalendarSync";
+import type { MainSynchronizer } from "Syncs/MainSynchronizer";
+import CalendarQuery from "ui/CalendarQuery.svelte";
+import ErrorDisplay from "ui/ErrorDisplay.svelte";
+import { debug } from "lib/DebugLog";
 
 import { parseQuery } from "./Parser";
-import { Query } from "./Query";
-
-import TodoistQuery from "../ui/TodoistQuery.svelte";
-import ErrorDisplay from "../ui/ErrorDisplay.svelte";
-import type { SvelteComponentDev } from "svelte/internal";
+import type { Query } from "./Query";
 
 export default class QueryInjector {
   private pendingQueries: PendingQuery[];
 
   private plugin: SyncCalendarPlugin;
-  private calendarSync: GoogleCalendarSync;
+  private mainSync: MainSynchronizer
 
   constructor(plugin: SyncCalendarPlugin) {
     this.plugin = plugin;
@@ -31,18 +30,17 @@ export default class QueryInjector {
       target: el,
       ctx: ctx,
     };
-    // console.log('source: ' + source);
 
-    if (typeof this.calendarSync == "undefined") {
+    if (typeof this.mainSync == "undefined") {
       this.pendingQueries.push(pendingQuery);
       return;
     }
 
     this.injectQuery(pendingQuery);
   }
 
-  setCalendarSync(calendarSync: GoogleCalendarSync) {
-    this.calendarSync = calendarSync;
+  setMainSync(mainSync: MainSynchronizer) {
+    this.mainSync = mainSync;
 
     while (this.pendingQueries.length > 0) {
       this.injectQuery(this.pendingQueries[0]);
@@ -60,30 +58,29 @@ export default class QueryInjector {
       }
 
       child = new InjectedQuery(pendingQuery.target, (root: HTMLElement) => {
-        return new TodoistQuery({
+        return new CalendarQuery({
           target: root,
           props: {
             plugin: this.plugin,
-            api: this.calendarSync,
+            api: this.mainSync,
             query: query,
           },
         });
       });
     }
-    catch (e) {
-      console.error(e);
+    catch (err) {
+      debug(`query error: ${err}`);
 
       child = new InjectedQuery(pendingQuery.target, (root: HTMLElement) => {
         return new ErrorDisplay({
           target: root,
           props: {
-            error: e
+            error: err
           },
         });
       });
     }
 
-
     pendingQuery.ctx.addChild(child);
   }
 

README.md

@@ -1,96 +1,98 @@
-# Obsidian Sample Plugin
-thanks to the brilliant plugins obsidian-todoist %% <a herf=""> %%
-This is a sample plugin for Obsidian (https://obsidian.md).
+# Obsidian x Calendar Plugin
 
-This project uses Typescript to provide type checking and documentation.
-The repo depends on the latest plugin API (obsidian.d.ts) in Typescript Definition format, which contains TSDoc comments describing what it does.
+An [Obsidian](https://obsidian.md/) plugin to materialize [Google Calendar](https://calendar.google.com/) events in Obsidian notes. [中文](./dcos/README.zh-Ch.md)
 
-**Note:** The Obsidian API is still in early alpha and is subject to change at any time!
 
-This sample plugin demonstrates some of the basic functionality the plugin API can do.
-- Changes the default font color to red using `styles.css`.
-- Adds a ribbon icon, which shows a Notice when clicked.
-- Adds a command "Open Sample Modal" which opens a Modal.
-- Adds a plugin setting tab to the settings page.
-- Registers a global click event and output 'click' to the console.
-- Registers a global interval which logs 'setInterval' to the console.
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dustinksi/obsidian-sync-calendar/release.yml?style=shield) ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/dustinksi/obsidian-sync-calendar?display_name=tag)
 
-## First time developing plugins?
 
-Quick starting guide for new plugin devs:
+**Note**: 
+1. Our task format is borrowed from tasks, but we **do not support recurring tasks** at the moment.
+2. To sync tasks from Obsidian to the calendar, you need to attach a start time element to the task (i.e. 🛫 YYYY-MM-DD), then click the sync icon or call the `Sync with Calendar` command.
+3. Our task synchronization is **centered around calendar events**, which means that after syncing tasks from Obsidian to the calendar, modifications to tasks in Obsidian will not be synced to the calendar. To further modify the schedule, you need to modify it directly in the calendar. The changes made in the calendar will be automatically synced back to Obsidian later.
+4. This plugin is still in early alpha and is subject to change at any time!
 
-- Check if [someone already developed a plugin for what you want](https://obsidian.md/plugins)! There might be an existing plugin similar enough that you can partner up with.
-- Make a copy of this repo as a template with the "Use this template" button (login to GitHub if you don't see it).
-- Clone your repo to a local development folder. For convenience, you can place this folder in your `.obsidian/plugins/your-plugin-name` folder.
-- Install NodeJS, then run `npm i` in the command line under your repo folder.
-- Run `npm run dev` to compile your plugin from `main.ts` to `main.js`.
-- Make changes to `main.ts` (or create new `.ts` files). Those changes should be automatically compiled into `main.js`.
-- Reload Obsidian to load the new version of your plugin.
-- Enable plugin in settings window.
-- For updates to the Obsidian API run `npm update` in the command line under your repo folder.
 
-## Releasing new releases
+![RELEASE DEMO](https://upic-openaccess.oss-cn-beijing.aliyuncs.com/picgo/README_DEMO.gif)
 
-- Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release.
-- Update your `versions.json` file with `"new-plugin-version": "minimum-obsidian-version"` so older versions of Obsidian can download an older version of your plugin that's compatible.
-- Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix `v`. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
-- Upload the files `manifest.json`, `main.js`, `styles.css` as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
-- Publish the release.
 
-> You can simplify the version bump process by running `npm version patch`, `npm version minor` or `npm version major` after updating `minAppVersion` manually in `manifest.json`.
-> The command will bump version in `manifest.json` and `package.json`, and add the entry for the new version to `versions.json`
+## Installation & Usage
 
-## Adding your plugin to the community plugin list
+### First of All
 
-- Check https://github.com/obsidianmd/obsidian-releases/blob/master/plugin-review.md
-- Publish an initial version.
-- Make sure you have a `README.md` file in the root of your repo.
-- Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin.
+- You need a Google Calendar credentials file. You can apply for it yourself:
+    - Refer [create project guide](https://developers.google.com/workspace/guides/create-project) to create a Google Cloud Project
+    - Refer [enable apis guide](https://developers.google.com/workspace/guides/enable-apis) to enable your Google Calendar's API.
+    - [Configure OA Screen](https://console.cloud.google.com/apis/credentials/consent?)
+    - [Prepare to get your OA credentials](https://console.cloud.google.com/apis/credentials/oauthclient)
+      - Select "Desktop Application"
+      - Input a name for this OA Application.
+      - Download the OAClient credentials file.
+- Place the credentials file in `VaultFolder/.obsidian/calendar.sync.credentials.json`
 
-## How to use
+### Manually installing the plugin
 
+- Download `main.js`, `styles.css`, `manifest.json` from the [release page](https://github.com/dustinksi/obsidian-sync-calendar/releases).
+- Copy the downloaded files to `VaultFolder/.obsidian/plugins/your-plugin-id/`.
+
+**Note**: You can also compile this plugin yourself:
 - Clone this repo.
-- `npm i` or `yarn` to install dependencies
-- `npm run dev` to start compilation in watch mode.
+- Run `npm i` or `yarn` to install dependencies.
+- Run `npm run dev` to start compilation in watch mode.
+
+
+### ~~From Obsidian Community Plugins Broswer (Not Avaliable for now.)~~
+- ~~Install the plugin through the Obsidian's community plugins browser.~~
+- ~~Enable the plugin in Obsidian.~~
+
+### Use this Plugin
+- Place a code block like the following in any note:
+   ````markdown
+   ```calendar-sync
+   name: "{numberTodo} todos @ Apr. 21",
+   timeMin: "2023-04-21"
+   timeMax: "2023-04-22"
+   ```
+   ````
+- Swap to preview mode and the plugin should replace this code block with the materialized result.
+
+> If you are synchronizing your vault, I recommend explicitly ignoring the `VaultFolder/.obsidian/calendar.sync.token.json` file for security reasons, if possible.
+
+## Inputs
+| Name |  Type | Description | Default |
+| ------------- | ---- | -------- | ------- |
+| `name`        | string        | The title for the query. You can use the `{numberTodos}` template which will be replaced by the number of todos returned by the query.        | {numberTodos} todos in calendar         |
+| `timeMin`      |      string   | A string that conforms to moment.js, the minimum time (including `timeMin`) for events.     |      One week before the current time   |
+| `timeMax` |      string    |  A string that conforms to moment.js, the maximum time (excluding `timeMax`) for events.   | null    |
+
+**Note**: 排序，过滤，按照标签等分组将在下一个版本推出，同时非常欢迎您提交 [Pull Request]()。
+
+## Command
+
+Currently, only one command is supported, which is used to manually trigger the synchronization of tasks from Obsidian to Calendar.
+
+`Sync with Calendar`:
+
+   This command will fetch tasks with a startDate (i.e. 🛫 YYYY-MM-DD) in Obsidian.
+
 
-## Manually installing the plugin
+## Thanks to  
 
-- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`.
+The brilliant plugins:
 
-## Improve code quality with eslint (optional)
-- [ESLint](https://eslint.org/) is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code. 
-- To use eslint with this project, make sure to install eslint from terminal:
-  - `npm install -g eslint`
-- To use eslint to analyze this project use this command:
-  - `eslint main.ts`
-  - eslint will then create a report with suggestions for code improvement by file and line number.
-- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder:
-  - `eslint .\src\`
+[obsidian-todoist](https://github.com/jamiebrynes7/obsidian-todoist-plugin)
 
-## Funding URL
+[obsidian-tasks](https://github.com/obsidian-tasks-group/obsidian-tasks) 
 
-You can include funding URLs where people who use your plugin can financially support it.
+[obsidian-dataview](https://github.com/blacksmithgu/obsidian-dataview)
 
-The simple way is to set the `fundingUrl` field to your link in your `manifest.json` file:
+This plugin has borrowed a lot of valuable experience from the above plugins.
 
-```json
-{
-    "fundingUrl": "https://buymeacoffee.com"
-}
-```
+And I would also like to thank Wang Jiayu for accompanying me through the conception, design, and development of this plugin.
 
-If you have multiple URLs, you can also do:
 
-```json
-{
-    "fundingUrl": {
-        "Buy Me a Coffee": "https://buymeacoffee.com",
-        "GitHub Sponsor": "https://github.com/sponsors",
-        "Patreon": "https://www.patreon.com/"
-    }
-}
-```
+## Support
 
-## API Documentation
+Have you found the obsidian-sync-calendar plugin helpful and want to support it? I accept donations that will go towards future development efforts. I generally do not accept payment for bug bounties/feature requests, as financial incentives add stress/expectations which I want to avoid for a hobby project!
 
-See https://github.com/obsidianmd/obsidian-api
+<a href="https://www.buymeacoffee.com/dexin.qi"><img src="https://img.buymeacoffee.com/button-api/?text=Buy me a cocacola&emoji=🥤&slug=dexin.qi&button_colour=FF5F5F&font_colour=ffffff&font_family=Cookie&outline_colour=000000&coffee_colour=FFDD00" /></a>