ns-nawah

此仓库是 ns-nawah 的源代码之家，Nawah SDK for Angular。

快速开始

当前 SDK 有两个依赖

• jsrasgin
• nativescript-websockets 依赖项应与库一起自动安装。

为 NativeScript 安装 ns-nawah

tns plugin add ns-nawah

如何使用

1. 在您的模块导入中导入 NsNawahModule。
2. 使用以下方式在组件中初始化 SDK

import { Component, OnInit } from '@angular/core';

import { NawahService, Res } from 'ns-nawah'

@Component({
	selector: 'app-root',
	templateUrl: './app.component.html',
	styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {

	constructor(private nawah: NawahService) {}

	ngOnInit() {
		this.nawah.init({
			api: 'ws://127.0.0.1:8081/ws',
			anonToken: '__ANON_TOKEN_f00000000000000000000012',
			authAttrs: ['email'],
			appId: 'APP_ID',
		});
	}
}

SDK 配置

初始化 SDK 时，您应传递一个符合 SDKConfig 接口的对象，它具有以下属性

1. api（必需）：您要连接的 Nawah 应用程序的 URI。
2. anonToken（必需）：Nawah 应用程序的 ANON_TOKEN。
3. authAttrs（必需）：Nawah 应用程序没有严格的 User 模块属性结构。这包括每个应用程序设置的认证属性。此属性表示一个 Array<string>，指向应用程序的相同认证属性。
4. debug（可选）：一个表示 SDK 调试模式状态的 Boolean。如果为 true，您将在浏览器控制台中看到有关传输和接收的消息的详细消息。默认 false。
5. fileChunkSize（可选）：一个表示作为将二进制数据推送到 Nawah 应用程序的过程的一部分上传的文件的字节数的 Number。默认 512000。

最佳实践

您可以按照自己的开发风格使用 SDK 100%，但我们有一些提示

会话重新认证

处理 reauth 场景的最佳实践是尽快尝试 checkAuth。这可以通过订阅 inited$ 主题来完成，该主题通知订阅关于 SDK 初始化状态的任何更改，该状态反映在 SDK 中的 inited 属性中。可以这样做

this.nawah.inited$.subscribe((init: boolean) => {
	if (init) {
		// SDK is inited and ready for your calls:
		try {
			// Wrap in try..catch to handle error thrown if no credentials cached
			this.nawah.checkAuth();
		} catch { }
	}
}, (err: Res<Doc>) => {
	console.log('inited$.err', err);
});

认证状态检测

尽管您可以在 auth、reauth 和 checkAuth 调用的订阅中检测用户认证状态，但最佳实践是使用全局的 authed$ 状态 Subject。您可以通过在初始化 SDK 的同一组件（通常是 AppComponent）中订阅 authed$ 来完成此操作。这确保了作为 api.init 订阅的一部分的成功 checkAuth 可以得到处理。建议的模型是

this.nawah.authed$.subscribe((session: Doc) => {
	if (session) {
		console.log('We are having an `auth` condition with session:', session);
	} else {
		console.log('We just got unauthenticated');
	}
});

断开连接时重新连接

WebSockets 是始终处于活跃状态的连接。这里可能会出错，导致与您的 Nawah 应用程序的连接中断。为了确保您始终可以重新连接，当 SDK 不再处于 inited 状态时，请调用 SDK 的 init 方法。

import { Component, OnInit } from '@angular/core';

import { NawahService, Res } from 'ns-nawah'

@Component({
	selector: 'app-root',
	templateUrl: './app.component.html',
	styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {

	constructor(private nawah: NawahService) {
		this.nawah.inited$.subscribe((init: boolean) => {
			if (init) {
				// SDK is inited and ready for your calls:
				try {
					// Wrap in try..catch to handle error thrown if no credentials cached
					this.nawah.checkAuth();
				} catch { }
			} else {
				// SDK just got not inited, let's init SDK again:
				this.init();
			}
		}, (err: Res<Doc>) => {
			console.log('inited$.err', err);
		});
	}

	ngOnInit() {
		this.init();
	}

	init(): void {
		this.nawah.init({
			api: 'ws://127.0.0.1:8081/ws',
			anonToken: '__ANON_TOKEN_f00000000000000000000012',
			authAttrs: ['email'],
			appId: 'APP_ID',
		});
	}
}

API 参考

debug

一个表示 SDK 上调试模式状态的 Boolean。如果为 true，您将在浏览器控制台中看到有关传输和接收的消息的详细消息。默认 false。

fileChunkSize

一个表示作为将二进制数据推送到 Nawah 应用程序的过程的一部分上传的文件的字节数的 Number。默认 512000。

session

一个表示当前会话的 Doc 对象。它仅在用户认证时才有值。

authed

一个存储用户当前认证状态的 Boolean。

authed$

您可以通过订阅 Subject<Boolean | Doc> 来处理用户认证状态的变化。

init()

与 Nawah 应用建立连接的基本方法。如果需要读取从 API 接收到的每条消息，则此方法返回一个 Observable 以进行链式订阅，尽管不需要订阅它。方法定义

init(api: String, anonToken: String): Observable<Res<Doc>> { /*...*/ }

close()

关闭当前与 Nawah 应用连接的方法。如果需要读取 close 调用的响应，则此方法返回一个 Observable 以进行链式订阅，尽管不需要订阅它。方法定义

close(): Observable<Res<Doc>> { /*...*/ }

auth()

您可以使用此方法进行用户认证。如果需要读取 auth 调用的响应，则此方法返回一个 Observable 以进行链式订阅，尽管不需要订阅它。方法定义

auth(authVar: string, authVal: string, password: string): Observable<Res<Doc>> { /*...*/ }

reauth()

您可以使用此方法重新认证用户。如果没有从先前的成功认证调用中缓存 sid 和 token 属性，则此方法将失败。此方法不应直接调用，而应使用 checkAuth()。如果需要读取 reauth 调用的响应，则此方法返回一个 Observable 以进行链式订阅，尽管不需要订阅它。方法定义

reauth(sid: string = this.cache.get('sid'), token: string = this.cache.get('token')): Observable<Res<Doc>> { /*...*/ }

signout()

您可以使用此方法注销当前用户。成功后，此方法将删除会话的所有缓存属性。如果需要读取 signout 调用的响应，则此方法返回一个 Observable 以进行链式订阅，尽管不需要订阅它。方法定义

signout(): Observable<Res<Doc>> { /*...*/ }

checkAuth()

检查是否存在缓存的会话并尝试重新认证用户的方法。如果没有缓存凭据，则此方法将抛出错误，因此您需要始终将其包裹在 try..catch 中。如果需要读取 checkAuth 调用的响应，则此方法返回一个 Observable 以进行链式订阅，尽管不需要订阅它。方法定义

checkAuth(): Observable<Res<Doc>> { /*...*/ }

generateAuthHash()

用于生成认证散列的方法。这用于内部 auth() 调用。但是，在创建用户时，您也需要此方法来生成值。方法定义

generateAuthHash(authVar: string, authVal: string, password: string): string { /*...*/ }

deleteWatch()

删除正在进行的监视的方法。您可以传递要删除的监视 ID 或 __all 以删除所有监视。如果需要读取 deleteWatch 调用的响应，则此方法返回一个 Observable 以进行链式订阅，尽管不需要订阅它。方法定义

deleteWatch(watch: string | '__all'): Observable<Res<Doc>> { /*...*/ }

call()

SDK 中最重要的方法。您使用此方法在 Nawah 应用中调用不同的端点。尽管 params 中的 callArgs 对象具有所有调用属性的完整定义，但在大多数情况下，您通常只需要传递 query 和/或 doc。第三个参数 awaitAuth 指定调用是否应排队等待会话认证。方法定义

call(endpoint: string, callArgs: callArgs, awaitAuth: boolean = false): Observable<Res<Doc>> { /*...*/ }

贡献指南

感谢您对 ns-nawah 的兴趣。

有关向本项目贡献的更多详细信息，请参阅 贡献指南。