appwrite-utils
Advanced tools
`appwrite-utils` is a comprehensive TypeScript library designed to streamline the development process for Appwrite projects. This library provides a suite of utilities and helper functions that facilitate data manipulation, schema management, YAML configu
appwrite-utils is a comprehensive TypeScript library designed to streamline the development process for Appwrite projects. This library provides a suite of utilities and helper functions that facilitate data manipulation, schema management, YAML configuration validation, and seamless integration with Appwrite services. Whether you're managing data migrations, schema updates, or building custom tools on top of the CLI architecture, appwrite-utils provides the foundation for professional Appwrite development.
Highlights:
databaseId or databaseIdscollections/documents/attributes and tables/rows/columnsTo integrate appwrite-utils into your project, ensure you have npm installed and run the following command in your project directory:
npm install appwrite-utils
appwrite-utils provides seamless support for both traditional Appwrite Collections API and the new TablesDB API, allowing you to work with either terminology based on your project needs.
collectionsdocumentsattributesDatabasestablesrowscolumnsTablesDBBoth APIs share the same underlying schema structure with dual terminology support:
import {
CollectionCreateSchema,
TableCreateSchema,
CollectionSchema,
TableSchema
} from "appwrite-utils";
// Collections API - Document-based terminology
const collection = CollectionCreateSchema.parse({
name: "Users",
attributes: [
{ key: "email", type: "string", required: true },
{ key: "name", type: "string", required: true }
],
indexes: [
{ key: "email_idx", type: "unique", attributes: ["email"] }
]
});
// TablesDB API - Table-based terminology
const table = TableCreateSchema.parse({
name: "Users",
attributes: [ // Note: Still uses 'attributes' internally for compatibility
{ key: "email", type: "string", required: true },
{ key: "name", type: "string", required: true }
],
indexes: [
{ key: "email_idx", type: "unique", attributes: ["email"] }
]
});
import type {
Collection,
Table,
CollectionCreate,
TableCreate
} from "appwrite-utils";
// Both types are structurally identical but semantically different
const handleCollection = (collection: Collection) => {
// Work with traditional collections
console.log(`Collection: ${collection.name}`);
console.log(`Attributes: ${collection.attributes.length}`);
};
const handleTable = (table: Table) => {
// Work with TablesDB tables
console.log(`Table: ${table.name}`);
console.log(`Columns: ${table.attributes.length}`); // Note: Still 'attributes' for compatibility
};
# .appwrite/config.yaml
databases:
- name: "main"
id: "main"
collections: # Collections terminology
- name: "Users"
id: "users"
attributes:
- key: "email"
type: "string"
required: true
# .appwrite/config.yaml
databases:
- name: "main"
id: "main"
tables: # TablesDB terminology
- name: "Users"
id: "users"
attributes: # Internally consistent with Collections
- key: "email"
type: "string"
required: true
import { CollectionCreateSchema, TableCreateSchema } from "appwrite-utils";
// Convert Collection definition to Table
const collectionConfig = {
name: "Users",
attributes: [{ key: "email", type: "string" }]
};
// Both schemas are compatible
const asCollection = CollectionCreateSchema.parse(collectionConfig);
const asTable = TableCreateSchema.parse(collectionConfig);
// Seamless interoperability
console.log(asCollection.name === asTable.name); // true
These functions help ensure the integrity and correctness of the data in your Appwrite projects:
isNumber,
isString,
isBoolean,
isArray,
isObject,
isNull,
isUndefined,
isDefined,
isDate,
isEmpty,
isInteger,
isFloat,
isArrayLike,
isArrayLikeObject,
isFunction,
isLength,
isMap,
isSet,
isRegExp,
isSymbol,
isObjectLike,
isPlainObject,
isSafeInteger,
isTypedArray,
isEqual,
isMatch,
has,
get;
Converters are designed to transform data formats or types to suit specific needs within your applications:
anyToString,
anyToNumber,
anyToBoolean,
anyToAnyArray,
anyToStringArray,
trySplitByDifferentSeparators,
removeStartEndQuotes,
splitByComma,
splitByPipe,
splitBySemicolon,
splitByColon,
splitBySlash,
splitByBackslash,
splitBySpace,
splitByDot,
splitByUnderscore,
splitByHyphen,
pickFirstElement,
pickLastElement,
stringifyObject,
parseObject,
safeParseDate,
removeInvalidElements,
joinValues,
joinBySpace,
joinByComma,
joinByPipe,
joinBySemicolon,
joinByColon,
joinBySlash,
joinByHyphen,
convertPhoneStringToUSInternational,
validateOrNullEmail;
These functions facilitate the management and operation of files within your Appwrite projects:
getFileViewUrl, getFileDownloadUrl;
Both getFileViewUrl and getFileDownloadUrl take parameters like endpoint, projectId, bucketId, fileId, and optionally jwt to generate accessible URLs for files stored in Appwrite.
After installing the package, you can directly import and use the various utilities in your TypeScript or JavaScript code. For example:
import { isNumber, anyToString } from "appwrite-utils";
// Use the functions directly in your code
console.log(isNumber(5)); // Output: true
console.log(anyToString(1234)); // Output: "1234"
This setup ensures that your interactions with Appwrite are more robust, less error-prone, and significantly more manageable.
Version 1.0.0 is designed to work seamlessly with appwrite-utils-cli's YAML-first architecture:
import {
YamlImportConfig,
AttributeMappings,
ValidationRules,
ConverterFunctions
} from "appwrite-utils";
// Type-safe YAML import configuration
const importConfig: YamlImportConfig = {
source: {
file: "importData/users.json",
basePath: "RECORDS",
type: "json"
},
target: {
collection: "Users",
type: "create",
primaryKey: "user_id",
createUsers: true
},
mapping: {
attributes: [
{
oldKey: "email",
targetKey: "email",
converters: ["anyToString", "stringToLowerCase"],
validation: [
{ rule: "email", params: ["{email}"] },
{ rule: "required", params: ["{email}"] }
]
}
]
}
};
import {
CollectionCreateSchema,
AttributeSchema,
AppwriteConfigSchema
} from "appwrite-utils";
// Validate YAML configurations with Zod schemas
const validatedConfig = AppwriteConfigSchema.parse(yamlConfig);
const validatedCollection = CollectionCreateSchema.parse(collectionData);
import {
convertObjectByAttributeMappings,
tryAwaitWithRetry,
parsePermissions,
getFileViewUrl,
objectNeedsUpdate,
cleanObjectForAppwrite,
listDocumentsBatched
} from "appwrite-utils";
// Data transformation used by CLI import system
const transformedData = convertObjectByAttributeMappings(sourceData, mappings);
// Retry logic for reliable API calls
const result = await tryAwaitWithRetry(() =>
databases.createDocument(dbId, collId, docId, data)
);
// Permission conversion for YAML configurations
const appwritePermissions = parsePermissions(yamlPermissions);
// Check if an object needs updating (ignores Appwrite system fields)
const needsUpdate = objectNeedsUpdate(existingDoc, updatedData);
// Clean object for Appwrite operations (removes system fields)
const cleanData = cleanObjectForAppwrite(dataWithSystemFields);
// Query documents in batches (Appwrite limits Query.equal to 100 IDs)
const documents = await listDocumentsBatched(
databases,
databaseId,
collectionId,
"$id",
arrayOfIds
);
🚀 Major Release - Full TablesDB Integration & Dual Terminology Support
TablesDB Schema Support: Complete type definitions for the new Appwrite TablesDB API
TableSchema, TableCreateSchema, and TablesSchema exportsDual Terminology Support: Native support for both API terminologies
collections, documents, attributestables, rows, columns (Note: internally uses attributes for compatibility)Enhanced Type Definitions: New TypeScript types for TablesDB integration
Table, Tables, TableCreate types exported alongside existing Collection typescollections and tables arrays// Collections Mode
import { CollectionCreateSchema } from "appwrite-utils";
// TablesDB Mode
import { TableCreateSchema } from "appwrite-utils";
// Both schemas accept identical configuration objects
const config = { name: "Users", attributes: [...] };
Migration Note: This release is fully backward compatible. Existing Collections API usage continues to work unchanged while TablesDB support is available for new projects or gradual migration.
twoWayKey and side are now optional unless twoWay: true.twoWay is enabled.🎉 Major Release - Zod v4 Compatibility & Performance Improvements
Optimized Attribute Creation: Fixed duplicate attribute creation issue
Fixed Index Creation: Resolved indexes not being created from collection configs
string[] instead of strictly typed enums for flexibilityIntegration Note: This version provides enhanced reliability for collection management operations and full Zod v4 compatibility.
🎉 Major Release - CLI Architecture Alignment
objectNeedsUpdate: Compares existing and updated objects, filtering out Appwrite system fields to determine if an update is neededcleanObjectForAppwrite: Removes Appwrite system fields ($id, $createdAt, $updatedAt, $permissions, etc.) from objects before create/update operationslistDocumentsBatched: Handles batched document queries since Appwrite only supports 100 IDs at a time in Query.equal()Integration Note: This version is specifically designed to work with appwrite-utils-cli 1.0.0's YAML-first architecture while maintaining full backward compatibility.
ulidx requirement as it was breaking Cloudflare Buildsstring[] var called ignore -- to ignore filesSpecificationSchema, type Specification type defs to support updating function specificationssafeParseDate to handle formats like 8:00AM vs 8:00 AM -- spaces matter!getFilePreviewUrl -- it was missing the & if you didn't use a JWTgetFilePreviewUrl which allows you to modify image files, or just get a preview of a fileparsePermissions which maps permissions to Appwrite stringsvalueToSet to attributeMappings, allowing you to set literal values in importDefstryAwaitWithRetry which retries failed API calls up to 5 timesID.unique() to ulid() for random ID generation, refactored schema filesTables and collections support both a single databaseId and multiple databaseIds for targeting multiple databases (e.g., dev/staging/main) with the same definition:
import { TableCreateSchema } from 'appwrite-utils';
const table = TableCreateSchema.parse({
name: 'Analytics',
databaseIds: ['dev', 'staging', 'main'],
attributes: [
{ key: 'timestamp', type: 'datetime', required: true },
{ key: 'totalUsers', type: 'integer' }
],
indexes: [{ key: 'ts_idx', type: 'key', attributes: ['timestamp'] }]
});
FAQs
`appwrite-utils` is a comprehensive TypeScript library designed to streamline the development process for Appwrite projects. This library provides a suite of utilities and helper functions that facilitate data manipulation, schema management, YAML configu
The npm package appwrite-utils receives a total of 186 weekly downloads. As such, appwrite-utils popularity was classified as not popular.
We found that appwrite-utils demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Node.js patched a crash bug where AsyncLocalStorage could cause stack overflows to bypass error handlers and terminate production servers.
Research
/Security News
A malicious Chrome extension steals newly created MEXC API keys, exfiltrates them to Telegram, and enables full account takeover with trading and withdrawal rights.
Security News
CVE disclosures hit a record 48,185 in 2025, driven largely by vulnerabilities in third-party WordPress plugins.