Replace typeshare with ts_rs for Typescript bindings (#316)

ts_rs supports the existing types without any modification. Removing the
dependency on typeshare and all the ffi modules and types.

Cargo.toml

@@ -34,7 +34,7 @@ strum = { version = "0.26.3", features = ["derive"] }
 tantivy = "0.22.0"
 tempfile = "3.10.1"
 thiserror = "1.0.63"
-typeshare = "1.0.3"
+ts-rs = {version = "9.0.1", features = ["chrono-impl", "no-serde-warnings"]}
 url = "2.5.2"
 ustr = { version = "1.0.0", features = ["serde"] }
 walkdir = "2.5.0"

Makefile

@@ -1,10 +1,11 @@
 # Run all build steps.
-build: build-ffi build-cargo
+build: generate-bindings build-cargo
 
-# Build and verify the FFI bindings.
-build-ffi:
-	typeshare ./ --lang=typescript --output-file=ffi/trane.ts
-	tsc ffi/trane.ts
+# Build and verify the TypeScript bindings.
+generate-bindings:
+	rm -rf bindings
+	cargo test --lib export_bindings
+	tsc --allowJs --noEmit bindings/*
 
 # Run all cargo checks and tests.
 build-cargo:

bindings/BasicAsset.ts

@@ -0,0 +1,19 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * An asset attached to a unit, which could be used to store instructions, or present the material
+ * introduced by a course or lesson.
+ */
+export type BasicAsset = { "MarkdownAsset": { 
+/**
+ * The path to the markdown file.
+ */
+path: string, } } | { "InlinedAsset": { 
+/**
+ * The content of the asset.
+ */
+content: string, } } | { "InlinedUniqueAsset": { 
+/**
+ * The content of the asset.
+ */
+content: string, } };

bindings/CourseGenerator.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { KnowledgeBaseConfig } from "./KnowledgeBaseConfig";
+import type { MusicPieceConfig } from "./MusicPieceConfig";
+import type { TranscriptionConfig } from "./TranscriptionConfig";
+
+/**
+ * A configuration used for generating special types of courses on the fly.
+ */
+export type CourseGenerator = { "KnowledgeBase": KnowledgeBaseConfig } | { "MusicPiece": MusicPieceConfig } | { "Transcription": TranscriptionConfig };

bindings/CourseManifest.ts

@@ -0,0 +1,60 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BasicAsset } from "./BasicAsset";
+import type { CourseGenerator } from "./CourseGenerator";
+
+/**
+ * A manifest describing the contents of a course.
+ */
+export type CourseManifest = { 
+/**
+ * The ID assigned to this course.
+ *
+ * For example, `music::instrument::guitar::basic_jazz_chords`.
+ */
+id: string, 
+/**
+ * The name of the course to be presented to the user.
+ *
+ * For example, "Basic Jazz Chords on Guitar".
+ */
+name: string, 
+/**
+ * The IDs of all dependencies of this course.
+ */
+dependencies: Array<string>, 
+/**
+ * The IDs of the courses or lessons that this course supersedes. If this course is mastered,
+ * then exercises from the superseded courses or lessons will no longer be shown to the
+ * student.
+ */
+superseded: Array<string>, 
+/**
+ * An optional description of the course.
+ */
+description: string | null, 
+/**
+ * An optional list of the course's authors.
+ */
+authors: Array<string> | null, 
+/**
+ * be attached to a course named "Basic Jazz Chords on Guitar".
+ *
+ * The purpose of this metadata is to allow students to focus on more specific material during
+ * a study session which does not belong to a single lesson or course. For example, a student
+ * might want to only focus on guitar scales or ear training.
+ */
+metadata: { [key: string]: Array<string> } | null, 
+/**
+ * An optional asset, which presents the material covered in the course.
+ */
+course_material: BasicAsset | null, 
+/**
+ * An optional asset, which presents instructions common to all exercises in the course.
+ */
+course_instructions: BasicAsset | null, 
+/**
+ * An optional configuration to generate material for this course. Generated courses allow
+ * easier creation of courses for specific purposes without requiring the manual creation of
+ * all the files a normal course would need.
+ */
+generator_config: CourseGenerator | null, };

bindings/ExerciseAsset.ts

@@ -0,0 +1,41 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BasicAsset } from "./BasicAsset";
+import type { TranscriptionLink } from "./TranscriptionLink";
+
+/**
+ * The asset storing the material of a particular exercise.
+ */
+export type ExerciseAsset = { "BasicAsset": BasicAsset } | { "FlashcardAsset": { 
+/**
+ * The path to the file containing the front of the flashcard.
+ */
+front_path: string, 
+/**
+ * The path to the file containing the back of the flashcard. This path is optional,
+ * because a flashcard is not required to provide an answer. For example, the exercise is
+ * open-ended, or it is referring to an external resource which contains the exercise and
+ * possibly the answer.
+ */
+back_path: string | null, } } | { "SoundSliceAsset": { 
+/**
+ * The link to the SoundSlice asset.
+ */
+link: string, 
+/**
+ * An optional description of the exercise tied to this asset. For example, "Play this
+ * slice in the key of D Major" or "Practice measures 1 through 4". A missing description
+ * implies the entire slice should be practiced as is.
+ */
+description: string | null, 
+/**
+ * An optional path to a MusicXML file containing the sheet music for the exercise.
+ */
+backup: string | null, } } | { "TranscriptionAsset": { 
+/**
+ * The content of the exercise.
+ */
+content: string, 
+/**
+ * An optional link to the audio for the exercise.
+ */
+external_link: TranscriptionLink | null, } };

bindings/ExerciseFilter.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { StudySessionData } from "./StudySessionData";
+import type { UnitFilter } from "./UnitFilter";
+
+/**
+ * A set of options to control which exercises should be considered to be included in the final
+ * batch.
+ */
+export type ExerciseFilter = { "UnitFilter": UnitFilter } | { "StudySession": StudySessionData };

bindings/ExerciseManifest.ts

@@ -0,0 +1,40 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ExerciseAsset } from "./ExerciseAsset";
+import type { ExerciseType } from "./ExerciseType";
+
+/**
+ * Manifest describing a single exercise.
+ */
+export type ExerciseManifest = { 
+/**
+ * The ID assigned to this exercise.
+ *
+ * For example, `music::instrument::guitar::basic_jazz_chords::major_chords::exercise_1`.
+ */
+id: string, 
+/**
+ * The ID of the lesson to which this exercise belongs.
+ */
+lesson_id: string, 
+/**
+ * The ID of the course to which this exercise belongs.
+ */
+course_id: string, 
+/**
+ * The name of the exercise to be presented to the user.
+ *
+ * For example, "Exercise 1".
+ */
+name: string, 
+/**
+ * An optional description of the exercise.
+ */
+description: string | null, 
+/**
+ * The type of knowledge the exercise tests.
+ */
+exercise_type: ExerciseType, 
+/**
+ * The asset containing the exercise itself.
+ */
+exercise_asset: ExerciseAsset, };

bindings/ExerciseTrial.ts

@@ -0,0 +1,14 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The result of a single trial.
+ */
+export type ExerciseTrial = { 
+/**
+ * The score assigned to the exercise after the trial.
+ */
+score: number, 
+/**
+ * The timestamp at which the trial happened.
+ */
+timestamp: bigint, };

bindings/ExerciseType.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The type of knowledge tested by an exercise.
+ */
+export type ExerciseType = "Declarative" | "Procedural";

bindings/FilterOp.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The logical operation used to combine multiple filters.
+ */
+export type FilterOp = "All" | "Any";

bindings/FilterType.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The type of filter according to whether the units which match are included or excluded.
+ */
+export type FilterType = "Include" | "Exclude";

bindings/Instrument.ts

@@ -0,0 +1,14 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Describes an instrument that can be used to practice in a generated course.
+ */
+export type Instrument = { 
+/**
+ * The name of the instrument. For example, "Tenor Saxophone".
+ */
+name: string, 
+/**
+ * An ID for this instrument used to generate lesson IDs. For example, "tenor_saxophone".
+ */
+id: string, };

bindings/KeyValueFilter.ts

@@ -0,0 +1,40 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FilterOp } from "./FilterOp";
+import type { FilterType } from "./FilterType";
+
+/**
+ * A filter on course or lesson metadata.
+ */
+export type KeyValueFilter = { "CourseFilter": { 
+/**
+ * The key to filter.
+ */
+key: string, 
+/**
+ * The value to filter.
+ */
+value: string, 
+/**
+ * Whether units which match the filter should be included or excluded.
+ */
+filter_type: FilterType, } } | { "LessonFilter": { 
+/**
+ * The key to filter.
+ */
+key: string, 
+/**
+ * The value to filter.
+ */
+value: string, 
+/**
+ * Whether units which match the filter should be included or excluded.
+ */
+filter_type: FilterType, } } | { "CombinedFilter": { 
+/**
+ * The logical operation used to combine multiple filters.
+ */
+op: FilterOp, 
+/**
+ * The filters to combine.
+ */
+filters: Array<KeyValueFilter>, } };

bindings/KnowledgeBaseConfig.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The configuration for a knowledge base course. Currently, this is an empty struct, but it is
+ * added for consistency with other course generators and to implement the [`GenerateManifests`]
+ * trait.
+ */
+export type KnowledgeBaseConfig = Record<string, never>;

bindings/LessonManifest.ts

@@ -0,0 +1,50 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BasicAsset } from "./BasicAsset";
+
+/**
+ * A manifest describing the contents of a lesson.
+ */
+export type LessonManifest = { 
+/**
+ * The ID assigned to this lesson.
+ *
+ * For example, `music::instrument::guitar::basic_jazz_chords::major_chords`.
+ */
+id: string, 
+/**
+ * The IDs of all dependencies of this lesson.
+ */
+dependencies: Array<string>, 
+/**
+ *The IDs of the courses or lessons that this lesson supersedes. If this lesson is mastered,
+ * then exercises from the superseded courses or lessons will no longer be shown to the
+ * student.
+ */
+superseded: Array<string>, 
+/**
+ * The ID of the course to which the lesson belongs.
+ */
+course_id: string, 
+/**
+ * The name of the lesson to be presented to the user.
+ *
+ * For example, "Basic Jazz Major Chords".
+ */
+name: string, 
+/**
+ * An optional description of the lesson.
+ */
+description: string | null, 
+/**
+ * be attached to a lesson named "C Major Scale". The purpose is the same as the metadata
+ * stored in the course manifest but allows finer control over which lessons are selected.
+ */
+metadata: { [key: string]: Array<string> } | null, 
+/**
+ * An optional asset, which presents the material covered in the lesson.
+ */
+lesson_material: BasicAsset | null, 
+/**
+ * An optional asset, which presents instructions common to all exercises in the lesson.
+ */
+lesson_instructions: BasicAsset | null, };

bindings/MasteryScore.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The score used by students to evaluate their mastery of a particular exercise after a trial.
+ * More detailed descriptions of the levels are provided using the example of an exercise that
+ * requires the student to learn a musical passage.
+ */
+export type MasteryScore = "One" | "Two" | "Three" | "Four" | "Five";

bindings/MasteryWindow.ts

@@ -0,0 +1,24 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A mastery window consists a range of scores and the percentage of the total exercises in the
+ * batch returned by the scheduler that will fall within that range.
+ *
+ * Mastery windows are used by the scheduler to control the amount of exercises for a given range
+ * of difficulty given to the student to try to keep an optimal balance. For example, exercises
+ * that are already fully mastered should not be shown very often lest the student becomes bored.
+ * Very difficult exercises should not be shown too often either lest the student becomes
+ * frustrated.
+ */
+export type MasteryWindow = { 
+/**
+ * The percentage of the exercises in each batch returned by the scheduler whose scores should
+ * fall within this window.
+ */
+percentage: number, 
+/**
+ * The range of scores which fall on this window. Scores whose values are in the range
+ * `[range.0, range.1)` fall within this window. If `range.1` is equal to 5.0 (the float
+ * representation of the maximum possible score), then the range becomes inclusive.
+ */
+range: [number, number], };