Merge pull request #1 from arnim279/use-deno

Switch to deno and refactor code

.github/workflows/check_formatting.yml

@@ -0,0 +1,18 @@
+name: Check formatting
+
+on: [push, pull_request]
+
+jobs:
+  check_formatting:
+    name: Check code formatting
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: denoland/setup-deno@v1
+        with:
+          deno-version: vx.x.x
+
+      - name: Check formatting
+        run: deno fmt --check

.github/workflows/publish.yml

@@ -1,29 +1,34 @@
-name: Publish to NPM
+name: Publish module
 
-on:
-  release:
-    types: [published]
+on: [release]
 
 jobs:
-  publish:
-    name: Build and publish to NPM
+  publish_npm:
+    name: Publish on NPM
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v3
 
-      - name: Set up Node
-        uses: actions/setup-node@v3
+      - uses: denoland/setup-deno@v1
+        with:
+          deno-version: vx.x.x
+
+      - uses: actions/setup-node@v3
         with:
           node-version: 18
-          registry-url: "https://registry.npmjs.org"
-          cache: npm
 
-      - name: Install dependencies
-        run: npm ci
+      - name: Get tag version
+        if: startsWith(github.ref, 'refs/tags/')
+        id: get_tag_version
+        run: echo ::set-output name=TAG_VERSION::${GITHUB_REF/refs\/tags\//}
+
+      - name: Transform to NPM package
+        run: deno task build_npm ${{steps.get_tag_version.outputs.TAG_VERSION}}
 
-      - name: Publish to NPM
-        run: npm publish --access public
+      - name: Publish on NPM
+        run: |
+          cd npm
+          npm publish
         env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Run Tests
+
+on: [push, pull_request]
+
+jobs:
+  run_tests:
+    name: Type-check code and run tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: denoland/setup-deno@v1
+        with:
+          deno-version: vx.x.x
+
+      - name: Type-check code
+        run: deno check mod.ts
+
+      - name: Type-check examples
+        run: | 
+          shopt -s globstar
+          for f in examples/**/*.ts; do deno check $f; done
+
+      - name: Run tests
+        run: deno test --allow-none --doc
+
+      - name: Lint code
+        run: deno lint --compact

.gitignore

@@ -1,2 +1 @@
-dist
-node_modules
+/npm

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["denoland.vscode-deno"]
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "deno.enable": true,
+  "typescript.validate.enable": false,
+  "editor.defaultFormatter": "denoland.vscode-deno"
+}

README.md

@@ -2,73 +2,77 @@
 
 ## About
 
-A client for accessing the [WebUntis](https://untis.com) API as documented [here](https://untis-sr.ch/wp-content/uploads/2019/11/2018-09-20-WebUntis_JSON_RPC_API.pdf).
+A client library for accessing the [WebUntis](https://untis.com) API following
+[this](https://untis-sr.ch/wp-content/uploads/2019/11/2018-09-20-WebUntis_JSON_RPC_API.pdf)
+documentation.
 
-As described in the [implementation details](#implementation-details), this client only uses the public API.
-If you need to use the internal API, check out [this library](https://github.com/SchoolUtils/WebUntis) instead.
+As described in the [implementation details](#implementation-details), this
+client only uses the public API. If you need to use the internal API, check out
+[this library](https://github.com/SchoolUtils/WebUntis) instead.
 
-## Usage
+This is a deno-first module, which means that even though there is an
+[NPM package](https://www.npmjs.com/package/untis-api-client), it will only work
+with Node.js 18+ (due to usage of `fetch()`) and ES Modules.
 
-### Installation
-
-```bash
-$ npm install untis-api-client
-```
-
-### Example
+## Example Usage
 
 ```ts
-import { LoginStatus, searchSchoolsByName } from "untis-api-client";
+import { LoginStatus, searchSchoolsByName } from "./mod.ts";
+
+let [school] = await searchSchoolsByName("School name");
 
-let [school] = await searchSchoolsByName("my school name");
 if (!school) {
-  throw new Error("school not found");
+  throw new Error("School not found");
 }
 
 let client = school.getClient();
 
 let status = await client.login("username", "password");
 
-if (!status.Ok) {
-  throw new Error(`Login failed: ${LoginStatus[status.value]}`);
+if (status !== LoginStatus.Ok) {
+  throw new Error(`Login failed: ${LoginStatus[status]}`);
 }
 
 let timetable = await client.getOwnTimetable("2022-01-01", "2022-12-31");
-client.logout();
+await client.logout();
 
-console.log(timetable);
+console.log(timetable.lessons);
 ```
 
 [More examples](examples/)
 
 ## Implementation details
 
-The client uses the "public" API. The official mobile WebUntis mobile apps and 3rd-party apps such as [BetterUntis](https://github.com/SapuSeven/BetterUntis) use the internal API,
-which allows you to log in anonymously or with an OTP.  
-Because I couldn't find any official documentation for it and the official API seemed more user-friendly, I didn't implement the internal API,
-so I don't know if either API has more or less features than the other one.  
-Also, not all documented methods are currently implemented in this client because I don't have the necessary permissions to access them, they are unavailable,
-or I don't need them in a backend environment. They are:
+The client uses the "public" API. The official mobile WebUntis mobile apps and
+3rd-party apps such as [BetterUntis](https://github.com/SapuSeven/BetterUntis)
+use the internal API, which allows you to log in anonymously or with an OTP.\
+Because I couldn't find any official documentation for it and the official API
+seemed more user-friendly, I didn't implement the internal API, so I don't know
+if either API has more or less features.\
+Also, not all documented methods are currently implemented in this client
+because I don't have the necessary permissions to access them, they are
+unavailable, or I don't need them in a backend environment. They are:
 
 - requesting departments (`getDepartments`)
-- requesting the time grid (`getTImegridUnits`)
+- requesting the time grid (`getTimegridUnits`)
 - requesting status data (`getStatusData`)
-- searching a person's id (`getPersonId`)
+- getting a person's id (`getPersonId`)
 - requesting substitutions (`getSubstitutions`)
 - getting exams or exam types (`getExams`, `getExamTypes`)
 - requesting a timetable with absences (`getTimetableWithAbsences`)
-- requesting class-reg events or remark categories (`getClassregEvents`, `getClassregCategories`, `getClassregCategoryGroups`)
+- requesting class-reg events or remark categories (`getClassregEvents`,
+  `getClassregCategories`, `getClassregCategoryGroups`)
 
 ## Contributing
 
-I am unable to test a lot of the WebUntis API features myself because
-they are undocumented, or I don't have permission to use them.
-Therefore, feel free to contribute to this API client!  
+As mentioned above, I am unable to test a lot of the API features myself because
+they are undocumented or I don't have the necessary permission to use them. So
+feel free to contribute to this API client!\
 Here are a few things you should keep in mind:
 
 - add tests wherever possible
 - test your additions thoroughly before committing
-- format your code using `npm run format:apply`
+- format your code using `deno fmt`
 
 ### Project structure
 

deno.jsonc

@@ -0,0 +1,35 @@
+{
+  "importMap": "import_map.json",
+
+  "lint": {
+    "files": { "exclude": ["npm"] },
+    "rules": {
+      "exclude": ["prefer-const"],
+      "include": [
+        "camelcase",
+        "explicit-function-return-type",
+        "explicit-module-boundary-types",
+        "eqeqeq",
+        "no-external-import",
+        "ban-untagged-todo"
+      ]
+    }
+  },
+
+  "test": {
+    "files": { "exclude": ["npm"] }
+  },
+
+  "fmt": {
+    "files": { "exclude": ["npm"] }
+  },
+
+  "tasks": {
+    "build_npm": "deno run -A scripts/build_npm.ts"
+  },
+
+  "compilerOptions": {
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true
+  }
+}