Iniciando
Visão geral e primeiros passos com o TileJS Database
Bem-vindo
O @tilejs/database é um banco de dados local, tipado e baseado em schemas para aplicações Node.js e Bun.
Ele foi desenvolvido para oferecer uma API simples, forte integração com TypeScript e armazenamento em arquivos BSON, sem depender de um servidor externo.
Se esta é sua primeira vez utilizando o TileJS Database, siga esta ordem de leitura:
Instalação → Database → Schema → Collections → CRUD
Principais recursos
100% TypeScript
Schemas totalmente tipados com autocompletar.
Sem servidor
Armazena todos os dados localmente em arquivos BSON.
Schemas
Validação, índices e configurações em um único lugar.
Leve
Ideal para CLIs, bots, APIs e aplicações locais.
Exemplo rápido
import { Database, Schema } from "@tilejs/database";
interface Member {
_id?: string;
email: string;
}
const memberSchema = new Schema<Member>({
_id: { type: String },
email: { type: String, unique: true },
});
const connection = new Database({
logger: {
enabled: true,
colors: true,
},
});
const database = Object.assign(connection, {
members: connection.collection<Member>("members", memberSchema),
});
console.log(database.members.describeSchema());Na primeira execução, o banco cria automaticamente a estrutura de diretórios, os índices e o schema da coleção.
Configuração do Database
Prop
Type
Estrutura criada
Após criar a primeira coleção, a estrutura do projeto ficará semelhante a esta:
A pasta .tile contém todos os arquivos da database e é criada automaticamente. Não é necessário criar ou editar esses arquivos manualmente.
Como funcionam os índices
Sempre que um campo do schema possuir unique: true, o TileJS cria automaticamente um arquivo de índice exclusivo para esse campo.
Esses índices permitem localizar registros rapidamente e garantem que valores únicos nunca sejam duplicados.
No exemplo acima, o schema foi definido assim:
const memberSchema = new Schema<Member>({
_id: { type: String },
email: { type: String, unique: true },
});Por isso, foram criados os arquivos:
_collection_index_id.json_collection_index_email.json
Índice do _id
Todo documento possui um _id único. O arquivo abaixo registra apenas a existência de cada identificador.
{
"6a3deee44f73903377c3cf0f": true
}Índice do email
Como email foi definido com unique: true, o índice armazena a relação entre o e-mail e o _id do documento.
{
"israel@gmail.com": "6a3deee44f73903377c3cf0f"
}Qualquer campo marcado com unique: true gera automaticamente um arquivo chamado collection_index<nome-do-campo>.json.
Isso permite que o TileJS verifique rapidamente se um valor já existe antes de inserir ou atualizar um documento, além de acelerar consultas por campos únicos.
Saída esperada
[2026-06-25T01:40:10.097Z] [DEBUG] Collection "members" created
schema: {
fields: {
_id: { ... },
email: { ... },
__v: { ... }
},
timestamps: true
}