@haverstack/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Stack — Core Type Definitions
+ * -------------------------------------------------------
+ * This file is the source of truth for all types in the
+ * Stack library. No logic lives here — just shapes.
+ */
+/**
+ * Crockford base-32 encoded ID — time-sortable, unique within a stack.
+ * Format: 9-char timestamp prefix + 3-char random suffix = 12 chars total.
+ * Human-readable and URL-safe. Uniqueness is within-stack only;
+ * cross-stack references must include a stackUrl to disambiguate.
+ */
+export type RecordId = string;
+/** Namespaced, versioned type identifier e.g. "com.example.myapp/note@2" */
+export type TypeId = string;
+/** Opaque file identifier returned by putAttachment */
+export type FileId = string;
+export type TagAssociation = {
+    kind: 'tag';
+    label: string;
+};
+export type AttachmentAssociation = {
+    kind: 'attachment';
+    label: string;
+    fileId: FileId;
+    mimeType: string;
+};
+export type RelationshipAssociation = {
+    kind: 'relationship';
+    label: string;
+    recordId: RecordId;
+};
+export type Association = TagAssociation | AttachmentAssociation | RelationshipAssociation;
+/**
+ * Grants of access to a Record. Absence of permissions (empty or undefined)
+ * means private — readable only by the stack owner. Permissions are
+ * declarative intent; enforcement is the API adapter's responsibility.
+ */
+export type Permission = {
+    access: 'public';
+} | {
+    access: 'entity';
+    entityId: RecordId;
+    read: boolean;
+    write: boolean;
+} | {
+    access: 'group';
+    groupId: RecordId;
+    read: boolean;
+    write: boolean;
+};
+export type StackRecord = {
+    id: RecordId;
+    typeId: TypeId;
+    createdAt: Date;
+    updatedAt: Date;
+    content: Record<string, unknown>;
+    version: number;
+    parentId?: RecordId;
+    entityId?: RecordId;
+    appId?: RecordId;
+    deletedAt?: Date;
+    permissions?: Permission[];
+    associations?: Association[];
+};
+export type RecordVersion = {
+    version: number;
+    content: Record<string, unknown>;
+    updatedAt: Date;
+    entityId?: RecordId;
+};
+export type ScalarFieldKind = 'string' | 'number' | 'boolean' | 'date' | 'text' | 'record-ref';
+export type ScalarFieldDef = {
+    kind: ScalarFieldKind;
+    required?: boolean;
+};
+export type ArrayFieldDef = {
+    kind: 'array';
+    items: FieldDef;
+    required?: boolean;
+};
+export type ObjectFieldDef = {
+    kind: 'object';
+    properties: TypeSchema;
+    required?: boolean;
+};
+/**
+ * A field definition in a Type schema. Supports scalars, arrays, and nested
+ * objects. Arrays and nested objects are schema-validated on write but are
+ * opaque to the query engine in v1 — only top-level scalar fields support
+ * exact-match content filtering in queries.
+ */
+export type FieldDef = ScalarFieldDef | ArrayFieldDef | ObjectFieldDef;
+export type TypeSchema = {
+    [fieldName: string]: FieldDef;
+};
+export type StackType = {
+    id: TypeId;
+    baseId: string;
+    version: number;
+    name: string;
+    schema: TypeSchema;
+    schemaHash: string;
+    migratesFrom?: TypeId;
+    createdAt: Date;
+};
+/** Content for _entity records */
+export type EntityContent = {
+    /** Display name — human-friendly, not necessarily unique. May contain spaces and punctuation. e.g. "Jane Smith" */
+    name: string;
+    /** Short unique identifier within a namespace — URL-safe, no spaces. e.g. "janesmith". Like a username. Optional for private entities. */
+    handle?: string;
+};
+/** Content for _app records */
+export type AppContent = {
+    /** Display name of the app e.g. "My Notes App" */
+    name: string;
+    /**
+     * Semver string e.g. "1.0.0". The app's unique machine-readable identity
+     * is already captured by the _app record's appId (e.g. "com.example.myapp"),
+     * so no handle is needed here.
+     */
+    version?: string;
+};
+/** Content for _group records */
+export type GroupContent = {
+    /** Display name — human-friendly, not necessarily unique. May contain spaces and punctuation. e.g. "Jane's Book Club" */
+    name: string;
+    /** Short unique identifier — URL-safe, no spaces. e.g. "janes-book-club". Useful for groups other people need to reference. Optional for private groups. */
+    handle?: string;
+    /** If present, this group owns a shared collaborative stack at this URL. Absent = permission-only group. */
+    stackUrl?: string;
+};
+/** Reserved system type IDs */
+export declare const SYSTEM_TYPES: {
+    readonly ENTITY: "_entity";
+    readonly APP: "_app";
+    readonly GROUP: "_group";
+};
+export type DateRange = {
+    before?: Date;
+    after?: Date;
+};
+export type RecordFilter = {
+    typeId?: TypeId | TypeId[];
+    parentId?: RecordId | null;
+    appId?: RecordId | RecordId[];
+    entityId?: RecordId | RecordId[];
+    createdAt?: DateRange;
+    updatedAt?: DateRange;
+    tags?: string[];
+    hasAttachment?: string;
+    relatedTo?: {
+        recordId: RecordId;
+        label?: string;
+    };
+    content?: Record<string, unknown>;
+    search?: string;
+    includeDeleted?: boolean;
+};
+export type QuerySort = {
+    field: 'createdAt' | 'updatedAt' | 'version';
+    direction?: 'asc' | 'desc';
+};
+export type StackQuery = {
+    filter?: RecordFilter;
+    sort?: QuerySort;
+    limit?: number;
+    cursor?: string;
+};
+export type QueryResult = {
+    records: StackRecord[];
+    cursor: string | null;
+    total: number;
+};
+export type MigrationFn = (content: Record<string, unknown>) => Record<string, unknown>;
+export type Migration = {
+    from: TypeId;
+    to: TypeId;
+    migrate: MigrationFn;
+};
+export type AdapterCapabilities = {
+    fullTextSearch: boolean;
+    contentFieldQuery: boolean;
+    sortableFields: Array<QuerySort['field']>;
+};
+/**
+ * Every storage backend implements this interface.
+ * The Stack class is a thin orchestration layer on top.
+ */
+export interface StackAdapter {
+    readonly capabilities: AdapterCapabilities;
+    getConfig(key: string): Promise<string | null>;
+    setConfig(key: string, value: string): Promise<void>;
+    createRecord(record: StackRecord): Promise<StackRecord>;
+    getRecord(id: RecordId): Promise<StackRecord | null>;
+    updateRecord(id: RecordId, changes: Partial<StackRecord>): Promise<StackRecord>;
+    deleteRecord(id: RecordId, opts?: {
+        hard?: boolean;
+    }): Promise<void>;
+    queryRecords(query: StackQuery): Promise<QueryResult>;
+    associate(id: RecordId, association: Association): Promise<void>;
+    dissociate(id: RecordId, association: Association): Promise<void>;
+    getVersions(id: RecordId): Promise<RecordVersion[]>;
+    getVersion(id: RecordId, version: number): Promise<RecordVersion | null>;
+    saveVersion(id: RecordId, version: RecordVersion): Promise<void>;
+    saveType(type: StackType): Promise<void>;
+    getType(id: TypeId): Promise<StackType | null>;
+    listTypes(): Promise<StackType[]>;
+    putAttachment(data: Uint8Array, mimeType: string): Promise<FileId>;
+    getAttachment(fileId: FileId): Promise<Uint8Array>;
+    deleteAttachment(fileId: FileId): Promise<void>;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Stack — Core Type Definitions
+ * -------------------------------------------------------
+ * This file is the source of truth for all types in the
+ * Stack library. No logic lives here — just shapes.
+ */
+/** Reserved system type IDs */
+export const SYSTEM_TYPES = {
+    ENTITY: '_entity',
+    APP: '_app',
+    GROUP: '_group',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiLH,+BAA+B;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,MAAM,EAAE,SAAS;IACjB,GAAG,EAAE,MAAM;IACX,KAAK,EAAE,QAAQ;CACP,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stack — Content Validation
+ * -------------------------------------------------------
+ * Validates a Record's content object against a TypeSchema.
+ * Returns a list of validation errors — empty means valid.
+ *
+ * Validates recursively for array and object field kinds.
+ * Coercion is never performed — types must match exactly.
+ */
+import type { TypeSchema } from './types.js';
+export type ValidationError = {
+    path: string;
+    message: string;
+};
+/**
+ * Validate content against a schema, collecting all errors.
+ * @param content  - The record's content object
+ * @param schema   - The TypeSchema to validate against
+ * @param prefix   - Internal: dot path prefix for nested validation
+ * @param errors   - Internal: error accumulator for recursive calls
+ */
+export declare const validateContent: (content: Record<string, unknown>, schema: TypeSchema, prefix?: string, errors?: ValidationError[]) => ValidationError[];
+/**
+ * Returns true if the content is valid against the schema.
+ * Use validateContent() directly to get error details.
+ */
+export declare const isValid: (content: Record<string, unknown>, schema: TypeSchema) => boolean;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAA6B,MAAM,YAAY,CAAC;AAMxE,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAqEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,UAAU,EAClB,eAAW,EACX,SAAQ,eAAe,EAAO,KAC7B,eAAe,EAiBjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,UAAU,KAAG,OAChC,CAAC"}

package/dist/validate.js

@@ -0,0 +1,92 @@
+/**
+ * Stack — Content Validation
+ * -------------------------------------------------------
+ * Validates a Record's content object against a TypeSchema.
+ * Returns a list of validation errors — empty means valid.
+ *
+ * Validates recursively for array and object field kinds.
+ * Coercion is never performed — types must match exactly.
+ */
+// -------------------------------------------------------
+// Internal helpers
+// -------------------------------------------------------
+const jsTypeForScalar = (kind) => {
+    switch (kind) {
+        case 'string':
+        case 'text':
+        case 'record-ref':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'date':
+            return 'string'; // Dates are transmitted as ISO 8601 strings
+    }
+};
+const validateField = (value, def, path, errors) => {
+    if (def.kind === 'array') {
+        if (!Array.isArray(value)) {
+            errors.push({ path, message: `Expected array, got ${typeof value}` });
+            return;
+        }
+        value.forEach((item, i) => validateField(item, def.items, `${path}[${i}]`, errors));
+        return;
+    }
+    if (def.kind === 'object') {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            errors.push({ path, message: `Expected object, got ${typeof value}` });
+            return;
+        }
+        validateContent(value, def.properties, path, errors);
+        return;
+    }
+    // Scalar validation
+    if (def.kind === 'date') {
+        if (typeof value !== 'string' || isNaN(Date.parse(value))) {
+            errors.push({
+                path,
+                message: `Expected ISO 8601 date string, got ${typeof value}`,
+            });
+        }
+        return;
+    }
+    const expected = jsTypeForScalar(def.kind);
+    if (typeof value !== expected) {
+        errors.push({
+            path,
+            message: `Expected ${expected}, got ${typeof value}`,
+        });
+    }
+};
+// -------------------------------------------------------
+// Public API
+// -------------------------------------------------------
+/**
+ * Validate content against a schema, collecting all errors.
+ * @param content  - The record's content object
+ * @param schema   - The TypeSchema to validate against
+ * @param prefix   - Internal: dot path prefix for nested validation
+ * @param errors   - Internal: error accumulator for recursive calls
+ */
+export const validateContent = (content, schema, prefix = '', errors = []) => {
+    // Check all schema fields
+    for (const [key, def] of Object.entries(schema)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        const value = content[key];
+        if (value === undefined || value === null) {
+            if (def.required) {
+                errors.push({ path, message: 'Required field is missing' });
+            }
+            continue;
+        }
+        validateField(value, def, path, errors);
+    }
+    return errors;
+};
+/**
+ * Returns true if the content is valid against the schema.
+ * Use validateContent() directly to get error details.
+ */
+export const isValid = (content, schema) => validateContent(content, schema).length === 0;
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@haverstack/core",
+  "version": "0.1.0",
+  "description": "Core library for Haverstack — portable personal data stack",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/haverstack/core",
+    "directory": "packages/core"
+  },
+  "license": "CC0-1.0",
+  "keywords": [
+    "haverstack",
+    "personal data",
+    "data stack",
+    "structured data",
+    "records",
+    "portable"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests"
+  }
+}