Flutter数据库交互插件surrealdb_js的使用

surrealdb_js

<surrealdb_js> 插件是一个强大的集成，为 Flutter 提供了对 SurrealDB 的支持。它基于 <surrealdb.js>，这是官方的 SurrealDB JavaScript SDK。

安装

在开始使用 surrealdb_js 之前，必须确保已经在机器上安装了 Flutter SDK。

通过 flutter pub add 安装

flutter pub add surrealdb_js

或者，手动添加到 pubspec.yaml

dependencies:
  surrealdb_js:

然后运行以下命令来安装依赖：

flutter pub get

最后，在 <web/index.html> 文件中添加以下代码：

<script type="module">
  import { Surreal, StringRecordId } from "/assets/packages/surrealdb_js/assets/js/index.js";
  // 将类型暴露给全局作用域
  globalThis.SurrealJS = Surreal;
  globalThis.StringRecordId = StringRecordId;
</script>

功能

• [x] connect()
• [x] close()
• [x] use()
• [x] create()
• [x] update()
• [x] merge()
• [x] delete()
• [x] select()
• [x] query()
• [x] query_raw()
• [x] transaction()
• [x] let()
• [x] unset()
• [x] signup()
• [x] signin()
• [x] invalidate()
• [x] authenticate()
• [x] info()
• [x] patch()
• [x] version()

示例

基本用法

final db = Surreal();

await db.connect('http://127.0.0.1:8000/rpc');
await db.use(namespace: 'surreal', database: 'surreal');
await db.signin({'username': 'root', 'password': 'root'});

final created = db.create('person',
      {
        'title': 'CTO',
        'name': {
          'first': 'Tom',
          'last': 'Jerry',
        },
        'marketing': true,
      },
    );

// created['id'] = person:b9eht8bie8abf0vbcfxh
final id = created['id'].toString();

final merged = await db.merge(
        id,
        {
          'marketing': false,
        },
      );

final tom = await db.select(id);

final deleted = await db.delete(id);

事务支持

final result = await db.transaction(
  showSql: true,
  (txn) async {
    txn.query('DEFINE TABLE test SCHEMAFULL;');
    txn.query('DEFINE FIELD name ON test TYPE string;');
    txn.query(
      r'CREATE test SET name = $name;',
      bindings: {'name': 'John'},
    );
    if (somethingWrong) {
      txn.cancel();
    }
  },
);

更多代码示例可以参见 integration test 和 example project。

贡献

欢迎贡献！请检查未实现的功能列表、仓库中的问题，并随时提交拉取请求。更多信息请查看 贡献指南。

许可证

该项目采用 MIT 许可证。

引用

如果使用此包，请考虑引用：

@misc{surrealdb_js,
  author = {Lim Chee Kin},
  title = {surrealdb_js: Flutter SurrealDB SDK for JavaScript package},
  year = {2024},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/limcheekin/surrealdb_js}},
}

示例代码

import 'package:flutter/material.dart';
import 'package:surrealdb_js/surrealdb_js.dart';
import 'package:flutter_console_widget/flutter_console.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter SurrealDB SDK for JavaScript Example',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatefulWidget {
  const HomePage({
    super.key,
  });

  [@override](/user/override)
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final FlutterConsoleController controller = FlutterConsoleController();
  final db = Surreal();
  static const commandSymbol = '>';

  Future<dynamic> execute(Function function, [String? message]) async {
    controller.print(
      message: '$commandSymbol $message',
      endline: false,
    );
    dynamic result;
    try {
      result = await function();
      controller.print(
        message: ' ✅',
        endline: true,
      );
      if (result != null) {
        debugPrint('homepage: result $result');
        if (result is Iterable) {
          if (result.isNotEmpty) {
            if (result.first is List) {
              // nested list for multiple statements
              if (result
                  .reduce((value, element) => value + element)
                  .isNotEmpty) {
                controller.print(
                  message: result.toString(),
                  endline: true,
                );
              }
            } else {
              controller.print(
                message: result.toString(),
                endline: true,
              );
            }
          }
        } else {
          controller.print(
            message: result.toString(),
            endline: true,
          );
        }
      }
    } catch (error, stackTrace) {
      controller.print(
        message: ' ❎ $error',
        endline: true,
      );
      controller.print(
        message: stackTrace.toString(),
        endline: true,
      );
    }
    return result;
  }

  Future<void> executeSurrealDbCodes() async {
    await execute(
      () => db.connect('http://127.0.0.1:8000/rpc'),
      'db.connect()',
    );

    await execute(
      () => db.use(namespace: 'surreal', database: 'surreal'),
      'db.use()',
    );

    await execute(
      () => db.version(),
      'db.version',
    );

    await execute(
      () => db.signin({'username': 'root', 'password': 'root'}),
      'db.signin()',
    );

    await execute(
      () {
        return db.query('INFO FOR NS');
      },
      'db.query() ns',
    );

    final created = await execute(
      () {
        return db.create(
          'person',
          {
            'title': 'CTO',
            'name': {
              'first': 'Tom',
              'last': 'Jerry',
            },
            'marketing': true,
          },
        );
      },
      'db.create()',
    );

    final id = created['id'].toString();
    await execute(
      () {
        return db.update(
          id,
          {
            'title': 'CTO',
            'name': {
              'first': 'Tom',
              'last': 'John',
            },
          },
        );
      },
      'db.update()',
    );

    await execute(
      () => db.merge(
        id,
        {
          'marketing': false,
        },
      ),
      'db.merge()',
    );

    await execute(
      () => db.patch(
        id,
        [
          {'op': 'replace', 'path': '/status', 'value': 'completed'},
        ],
      ),
      'db.patch()',
    );

    // 批量插入
    await execute(
      () {
        final people = [
          {
            'title': 'CEO',
            'name': {
              'first': 'John',
              'last': 'Dow',
            },
            'marketing': true,
          },
          {
            'title': 'COO',
            'name': {
              'first': 'Gavin',
              'last': 'Law',
            },
            'marketing': true,
          },
        ];
        final result = db.query(
          'INSERT INTO person \$people',
          bindings: {
            'people': people,
          },
        );
        return result;
      },
      'db.query() batch inserts',
    );

    await execute(
      () => db.select('person'),
      'db.select()',
    );

    await execute(
      () {
        final groups = db.query(
          'SELECT marketing, count() FROM type::table(\$table) GROUP BY marketing',
          bindings: {
            'table': 'person',
          },
        );
        return groups;
      },
      'db.query() grouping',
    );

    await execute(
      () => db.delete('person'),
      'db.delete()',
    );
  }

  [@override](/user/override)
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) async {
      await executeSurrealDbCodes();
      echoLoop();
    });
  }

  void echoLoop() {
    controller.scan().then((value) {
      execute(
        () => db.query(value),
        value,
      );
      controller.focusNode.requestFocus();
      echoLoop();
    });
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    final size = MediaQuery.of(context).size;
    return Scaffold(
      appBar: AppBar(
        title: const Text('Flutter SurrealDB SDK for JavaScript Example'),
      ),
      body: FlutterConsole(
        controller: controller,
        height: size.height,
        width: size.width,
      ),
    );
  }
}