0.1.13 • Published 4 months ago
@temboplus/afloat v0.1.13
@temboplus/afloat
A foundational library for Temboplus-Afloat projects.
This JavaScript/TypeScript package provides a central hub for shared utilities, logic, and data access mechanisms within the Temboplus-Afloat ecosystem.
Key Features
Abstracted Server Communication
- Simplifies front-end development by abstracting all interactions with the server behind model-specific repositories
- Consuming projects only need to interact with these repositories, decoupling them from the underlying API implementation
Shared Utilities
- Provides a collection of reusable helper functions for common tasks across Afloat projects, such as error handling
Data Models
- Defines standardized data structures and interfaces for consistent data representation throughout the Afloat ecosystem
Enhanced Maintainability
- Centralizes common logic, making it easier to maintain and update across all consuming projects
- Reduces code duplication and improves consistency
Cross-Environment Compatibility
- Works seamlessly in both client-side and server-side environments
- Supports both synchronous and asynchronous initialization patterns
Usage
Authentication Setup
Client-Side Usage
In client-side applications, authentication is initialized synchronously:
import { AfloatAuth } from "@temboplus/afloat";
// Initialize client auth (typically in your app entry point)
const auth = AfloatAuth.instance;
// Check if user is authenticated
console.log("User authenticated:", !!auth.currentUser);
// Access current user
const user = auth.currentUser;
if (user) {
console.log(`Logged in as: ${user.email}`);
}
Server-Side Usage
In server-side environments, authentication requires asynchronous initialization:
import { AfloatAuth } from "@temboplus/afloat";
// In a server route handler or similar context
async function handleRequest(req, res) {
try {
// Extract token from request
const token = req.headers.authorization?.replace('Bearer ', '');
if (!token) {
return res.status(401).json({ error: 'Unauthorized' });
}
// Initialize server-side auth
const auth = await AfloatAuth.initializeServer(token);
// Now you can use auth for permission checks
const isAdmin = auth.checkPermission(Permissions.Payout.View);
// Continue with your handler logic...
} catch (error) {
console.error('Authentication error:', error);
return res.status(500).json({ error: 'Authentication failed' });
}
}
Using Repositories
Repositories provide a consistent interface for data operations across environments.
Client-Side Repository Usage
import { WalletRepo } from "@temboplus/afloat";
// Create repository - auth is automatically handled
const walletRepo = new WalletRepo();
// Use repository methods
async function displayBalance() {
try {
const balance = await walletRepo.getBalance();
console.log(`Current balance: ${balance}`);
} catch (error) {
console.error('Error fetching balance:', error);
}
}
Server-Side Repository Usage
import { AfloatAuth, WalletRepo } from "@temboplus/afloat";
async function processServerRequest(token) {
// Initialize auth for this request
const auth = await AfloatAuth.initializeServer(token);
// Create repository with explicit auth instance
const walletRepo = new WalletRepo({ auth });
// Use repository methods
const balance = await walletRepo.getBalance();
const wallets = await walletRepo.getWallets();
return { balance, wallets };
}
Best Practices
Client-Side Applications
- Initialize
AfloatAuth.instance
early in your application lifecycle - Create repositories without explicit auth parameters
- Handle permission errors appropriately in your UI
- Initialize
Server-Side Applications
- Always use
await AfloatAuth.initializeServer(token)
for each request - Pass the auth instance explicitly to repositories
- Implement proper error handling for authentication failures
- Always use
Testing
- Use the
AuthContext
to inject mock auth instances during testing - Reset
AuthContext.current
after each test to prevent test pollution
- Use the