Add Getting Started docs for sqljs driver (cashapp#2261)

* Add getting started docs for sqljs driver

Fix dokka issue with Kotlin/JS modules

* Add multiplatform guidance for SqlJs driver

Remove "resources" page for Js docs

* Add required webpack config

docs/js_sqlite/coroutines.md

@@ -0,0 +1 @@
+{% include 'common/coroutines-multiplatform.md' %}

docs/js_sqlite/custom_projections.md

@@ -0,0 +1 @@
+{% include 'common/custom_projections.md' %}

docs/js_sqlite/gradle.md

@@ -0,0 +1 @@
+{% include 'common/gradle-multiplatform.md' %}

docs/js_sqlite/grouping_statements.md

@@ -0,0 +1 @@
+{% include 'common/grouping_statements.md' %}

docs/js_sqlite/index.md

@@ -0,0 +1,46 @@
+# Getting started on Kotlin JS with SQLDelight
+
+{% include 'common/index_gradle_database.md' %}
+
+{% include 'common/index_schema.md' %}
+
+```groovy
+kotlin {
+  sourceSets.jsMain.dependencies {
+    implementation "com.squareup.sqldelight:sqljs-driver:{{ versions.sqldelight }}"
+  }
+}
+```
+Unlike on other platforms, the SqlJs driver can not be instantiated directly.
+The driver must be loaded asynchronously by calling the `initSqlDriver` function which returns a `Promise<SqlDriver>`.
+```kotlin
+// As a Promise
+val promise: Promise<SqlDriver> = initSqlDriver(Database.Schema)
+promise.then { driver -> /* ... */ }
+
+// In a coroutine
+suspend fun createDriver() {
+    val driver: SqlDriver = initSqlDriver(Database.Schema).await()
+    /* ... */
+}
+```
+
+If building for browsers, some additional webpack configuration is also required.
+```js
+// project/webpack.conf.d/fs.js
+config.node = {
+    fs: 'empty'
+};
+
+// project/webpack.conf.d/wasm.js
+var CopyWebpackPlugin = require('copy-webpack-plugin');
+config.plugins.push(
+    new CopyWebpackPlugin([
+        { from: '../../node_modules/sql.js/dist/sql-wasm.wasm',
+            to: '../../../{your project}/build/distributions' }
+    ])
+);
+
+```
+
+{% include 'common/index_queries.md' %}

docs/js_sqlite/intellij_plugin.md

@@ -0,0 +1 @@
+{% include 'common/intellij_plugin.md' %}

docs/js_sqlite/migrations.md

@@ -0,0 +1 @@
+{% include 'common/migrations.md' %}

docs/js_sqlite/multiplatform.md

@@ -0,0 +1,82 @@
+# Multiplatform setup with the SqlJs Driver
+
+{% include 'common/index_gradle_database.md' %}
+
+{% include 'common/index_schema.md' %}
+
+```groovy
+kotlin {
+  // The drivers needed will change depending on what platforms you target:
+
+  sourceSets.androidMain.dependencies {
+    implementation "com.squareup.sqldelight:android-driver:{{ versions.sqldelight }}"
+  }
+
+  // or sourceSets.iosMain, sourceSets.windowsMain, etc.
+  sourceSets.nativeMain.dependencies {
+    implementation "com.squareup.sqldelight:native-driver:{{ versions.sqldelight }}"
+  }
+
+  sourceSets.jvmMain.dependencies {
+    implementation "com.squareup.sqldelight:sqlite-driver:{{ versions.sqldelight }}"
+  }
+
+  sourceSets.jsMain.dependencies {
+    implementation "com.squareup.sqldelight:sqljs-driver:{{ versions.sqldelight }}"
+  }
+}
+```
+
+Because the SqlJs driver must be initialized asynchronously, the drivers for other platforms must be initialized in a compatible way to be usable in a common source set.
+
+The drivers can be initialized in a coroutine, and a higher-order function can be used to ensure that the driver is initialized before executing a block of code that requires the database:
+
+```kotlin
+// in src/commonMain/kotlin
+expect suspend fun provideDbDriver(schema: SqlDriver.Schema): SqlDriver
+
+class SharedDatabase(
+    private val driverProvider: suspend (SqlDriver.Schema) -> SqlDriver
+) {
+    private var database: Database? = null
+
+    suspend fun initDatabase() {
+        if (database == null) {
+            database = driverProvider(Database.Schema).createDatabase()
+        }
+    }
+
+    suspend operator fun <R> invoke(block: suspend (Database) -> R): R {
+        initDatabase()
+        return block(database!!)
+    }
+
+    private fun SqlDriver.createDatabase(): Database { /* ... */ }
+}
+
+val sharedDb = SharedDatabase(::createTestDbDriver)
+class DataRepository(
+    private val withDatabase: SharedDatabase = sharedDb
+) {
+    suspend fun getData() = withDatabase { database ->
+        /* Do something with the database */
+    }
+}
+
+// in src/jsMain/kotlin
+actual suspend fun provideDbDriver(schema: SqlDriver.Schema): SqlDriver {
+    return initSqlDriver(schema).await()
+}
+
+// in src/nativeMain/kotlin
+actual suspend fun provideDbDriver(schema: SqlDriver.Schema): SqlDriver {
+    return NativeSqliteDriver(schema, "test.db")
+}
+
+// in src/jvmMain/kotlin
+actual suspend fun provideDbDriver(schema: SqlDriver.Schema): SqlDriver {
+    return JdbcSqliteDriver(JdbcSqliteDriver.IN_MEMORY).also { driver ->
+        schema.create(driver)
+    }
+}
+```

docs/js_sqlite/query_arguments.md

@@ -0,0 +1 @@
+{% include 'common/query_arguments_sqlite.md' %}

docs/js_sqlite/transactions.md

@@ -0,0 +1 @@
+{% include 'common/transactions.md' %}

docs/js_sqlite/types.md

@@ -0,0 +1,3 @@
+{% include 'common/types_sqlite.md' %}
+
+{% include 'common/custom_column_types.md' %}

docs/multiplatform_sqlite/index.md

@@ -60,4 +60,6 @@ actual class DriverFactory {
 }
 ```
 
+For use with the SqlJs driver, [see here](../js_sqlite/multiplatform).
+
 {% include 'common/index_queries.md' %}

drivers/sqljs-driver/build.gradle

@@ -29,3 +29,6 @@ kotlin {
 }
 
 apply from: "$rootDir/gradle/gradle-mvn-push.gradle"
+
+// https://github.com/Kotlin/dokka/issues/1455
+tasks.getByName("dokkaGfm").dependsOn(tasks.getByName("build"))

mkdocs.yml

@@ -142,6 +142,25 @@ nav:
         - 'sqlite-driver': 1.x/sqlite-driver/index.md
         - 'runtime': 1.x/runtime/index.md
 
+  - 'SQLite (JS)':
+      - 'Getting Started': js_sqlite/index.md
+      - 'Multiplatform': js_sqlite/multiplatform.md
+      - 'SQL':
+          - 'Projections': js_sqlite/custom_projections.md
+          - 'Arguments': js_sqlite/query_arguments.md
+          - 'Types': js_sqlite/types.md
+          - 'Transactions': js_sqlite/transactions.md
+          - 'Grouping Statements': js_sqlite/grouping_statements.md
+      - 'Extensions':
+          - 'Coroutines': js_sqlite/coroutines.md
+      - 'Migrations': js_sqlite/migrations.md
+      - 'IntelliJ Plugin': js_sqlite/intellij_plugin.md
+      - 'Gradle': js_sqlite/gradle.md
+      - '1.x API':
+          - 'coroutines-extensions': 1.x/coroutines-extensions/index.md
+          - 'sqljs-driver': 1.x/sqljs-driver/index.md
+          - 'runtime': 1.x/runtime/index.md
+
   - '1.x API':
       - 'android-driver': 1.x/android-driver/index.md
       - 'android-paging': 1.x/android-paging/index.md
@@ -152,6 +171,7 @@ nav:
       - 'rxjava2-extensions': 1.x/rxjava2-extensions/index.md
       - 'rxjava3-extensions': 1.x/rxjava3-extensions/index.md
       - 'sqlite-driver': 1.x/sqlite-driver/index.md
+      - 'sqljs-driver': 1.x/sqljs-driver/index.md
       - 'Internal':
         - 'sqldelight-compiler': 1.x/sqldelight-compiler/index.md
         - 'sqldelight-gradle-plugin': 1.x/sqldelight-gradle-plugin/index.md