kitedb 0.2.2

package/dist/schema.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Schema Definition API for RayDB
+ *
+ * Provides type-safe schema builders for defining graph nodes and edges.
+ *
+ * @example
+ * ```typescript
+ * import { node, edge, prop, optional } from '@ray-db/core'
+ *
+ * const User = node('user', {
+ *   key: (id: string) => `user:${id}`,
+ *   props: {
+ *     name: prop.string('name'),
+ *     email: prop.string('email'),
+ *     age: optional(prop.int('age')),
+ *   },
+ * })
+ *
+ * const knows = edge('knows', {
+ *   since: prop.int('since'),
+ * })
+ * ```
+ */
+/** Property type identifiers */
+export type PropType = 'string' | 'int' | 'float' | 'bool' | 'vector' | 'any';
+/** Property specification */
+export interface PropSpec {
+    /** Property type */
+    type: PropType;
+    /** Whether this property is optional */
+    optional?: boolean;
+    /** Default value for this property */
+    default?: unknown;
+}
+/**
+ * Property type builders.
+ *
+ * Use these to define typed properties on nodes and edges.
+ *
+ * @example
+ * ```typescript
+ * const name = prop.string('name')        // required string
+ * const age = optional(prop.int('age'))   // optional int
+ * const score = prop.float('score')       // required float
+ * const active = prop.bool('active')      // required bool
+ * const embedding = prop.vector('embedding', 1536)  // vector with dimensions
+ * ```
+ */
+export declare const prop: {
+    /**
+     * String property.
+     * Stored as UTF-8 strings.
+     */
+    string: (_name: string) => PropSpec;
+    /**
+     * Integer property.
+     * Stored as 64-bit signed integers.
+     */
+    int: (_name: string) => PropSpec;
+    /**
+     * Float property.
+     * Stored as 64-bit IEEE 754 floats.
+     */
+    float: (_name: string) => PropSpec;
+    /**
+     * Boolean property.
+     */
+    bool: (_name: string) => PropSpec;
+    /**
+     * Vector property for embeddings.
+     * Stored as Float32 arrays.
+     *
+     * @param _name - Property name
+     * @param _dimensions - Vector dimensions (for documentation/validation)
+     */
+    vector: (_name: string, _dimensions?: number) => PropSpec;
+    /**
+     * Any property (schema-less).
+     * Accepts any value type.
+     */
+    any: (_name: string) => PropSpec;
+};
+/**
+ * Mark a property as optional.
+ *
+ * @example
+ * ```typescript
+ * const age = optional(prop.int('age'))
+ * ```
+ */
+export declare function optional<T extends PropSpec>(spec: T): T;
+/**
+ * Set a default value for a property.
+ *
+ * @example
+ * ```typescript
+ * const status = withDefault(prop.string('status'), 'active')
+ * ```
+ */
+export declare function withDefault<T extends PropSpec>(spec: T, value: unknown): T;
+/** Key generation strategy */
+export interface KeySpec {
+    /** Key generation kind */
+    kind: 'prefix' | 'template' | 'parts';
+    /** Key prefix (for all kinds) */
+    prefix?: string;
+    /** Template string with {field} placeholders (for 'template' kind) */
+    template?: string;
+    /** Field names to concatenate (for 'parts' kind) */
+    fields?: string[];
+    /** Separator between parts (for 'parts' kind, default ':') */
+    separator?: string;
+}
+/** Node type specification */
+export interface NodeSpec {
+    /** Node type name (must be unique per database) */
+    name: string;
+    /** Key generation specification */
+    key?: KeySpec;
+    /** Property definitions */
+    props?: Record<string, PropSpec>;
+}
+/** Configuration for node() */
+export interface NodeConfig<K extends string = string> {
+    /**
+     * Key generator function or key specification.
+     *
+     * If a function is provided, it will be analyzed to extract the key prefix.
+     *
+     * @example
+     * ```typescript
+     * // Function form - prefix is extracted automatically
+     * key: (id: string) => `user:${id}`
+     *
+     * // Object form - explicit specification
+     * key: { kind: 'prefix', prefix: 'user:' }
+     * key: { kind: 'template', template: 'user:{org}:{id}' }
+     * key: { kind: 'parts', fields: ['org', 'id'], separator: ':' }
+     * ```
+     */
+    key?: ((arg: K) => string) | KeySpec;
+    /** Property definitions */
+    props?: Record<string, PropSpec>;
+}
+/**
+ * Define a node type with properties.
+ *
+ * Creates a node definition that can be used for all node operations
+ * (insert, update, delete, query).
+ *
+ * @param name - The node type name (must be unique)
+ * @param config - Node configuration with key function and properties
+ * @returns A NodeSpec that can be passed to ray()
+ *
+ * @example
+ * ```typescript
+ * const User = node('user', {
+ *   key: (id: string) => `user:${id}`,
+ *   props: {
+ *     name: prop.string('name'),
+ *     email: prop.string('email'),
+ *     age: optional(prop.int('age')),
+ *   },
+ * })
+ *
+ * // With template key
+ * const OrgUser = node('org_user', {
+ *   key: { kind: 'template', template: 'org:{org}:user:{id}' },
+ *   props: {
+ *     name: prop.string('name'),
+ *   },
+ * })
+ * ```
+ */
+export declare function node<K extends string = string>(name: string, config?: NodeConfig<K>): NodeSpec;
+/** Edge type specification */
+export interface EdgeSpec {
+    /** Edge type name (must be unique per database) */
+    name: string;
+    /** Property definitions */
+    props?: Record<string, PropSpec>;
+}
+/**
+ * Define an edge type with optional properties.
+ *
+ * Creates an edge definition that can be used for all edge operations
+ * (link, unlink, query). Edges are directional and can have properties.
+ *
+ * @param name - The edge type name (must be unique)
+ * @param props - Optional property definitions
+ * @returns An EdgeSpec that can be passed to ray()
+ *
+ * @example
+ * ```typescript
+ * // Edge with properties
+ * const knows = edge('knows', {
+ *   since: prop.int('since'),
+ *   weight: optional(prop.float('weight')),
+ * })
+ *
+ * // Edge without properties
+ * const follows = edge('follows')
+ * ```
+ */
+export declare function edge(name: string, props?: Record<string, PropSpec>): EdgeSpec;
+/** @deprecated Use `node()` instead */
+export declare const defineNode: typeof node;
+/** @deprecated Use `edge()` instead */
+export declare const defineEdge: typeof edge;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../ts/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,gCAAgC;AAChC,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAE7E,6BAA6B;AAC7B,MAAM,WAAW,QAAQ;IACvB,oBAAoB;IACpB,IAAI,EAAE,QAAQ,CAAA;IACd,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAMD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI;IACf;;;OAGG;oBACa,MAAM,KAAG,QAAQ;IAEjC;;;OAGG;iBACU,MAAM,KAAG,QAAQ;IAE9B;;;OAGG;mBACY,MAAM,KAAG,QAAQ;IAEhC;;OAEG;kBACW,MAAM,KAAG,QAAQ;IAE/B;;;;;;OAMG;oBACa,MAAM,gBAAgB,MAAM,KAAG,QAAQ;IAEvD;;;OAGG;iBACU,MAAM,KAAG,QAAQ;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAE1E;AAMD,8BAA8B;AAC9B,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAA;IACrC,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD,8BAA8B;AAC9B,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;CACjC;AAED,+BAA+B;AAC/B,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACnD;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,OAAO,CAAA;IACpC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CA2B9F;AAMD,8BAA8B;AAC9B,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAE7E;AAMD,uCAAuC;AACvC,eAAO,MAAM,UAAU,aAAO,CAAA;AAE9B,uCAAuC;AACvC,eAAO,MAAM,UAAU,aAAO,CAAA"}

package/dist/schema.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Schema Definition API for RayDB
+ *
+ * Provides type-safe schema builders for defining graph nodes and edges.
+ *
+ * @example
+ * ```typescript
+ * import { node, edge, prop, optional } from '@ray-db/core'
+ *
+ * const User = node('user', {
+ *   key: (id: string) => `user:${id}`,
+ *   props: {
+ *     name: prop.string('name'),
+ *     email: prop.string('email'),
+ *     age: optional(prop.int('age')),
+ *   },
+ * })
+ *
+ * const knows = edge('knows', {
+ *   since: prop.int('since'),
+ * })
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineEdge = exports.defineNode = exports.prop = void 0;
+exports.optional = optional;
+exports.withDefault = withDefault;
+exports.node = node;
+exports.edge = edge;
+// =============================================================================
+// Property Builders
+// =============================================================================
+/**
+ * Property type builders.
+ *
+ * Use these to define typed properties on nodes and edges.
+ *
+ * @example
+ * ```typescript
+ * const name = prop.string('name')        // required string
+ * const age = optional(prop.int('age'))   // optional int
+ * const score = prop.float('score')       // required float
+ * const active = prop.bool('active')      // required bool
+ * const embedding = prop.vector('embedding', 1536)  // vector with dimensions
+ * ```
+ */
+exports.prop = {
+    /**
+     * String property.
+     * Stored as UTF-8 strings.
+     */
+    string: (_name) => ({ type: 'string' }),
+    /**
+     * Integer property.
+     * Stored as 64-bit signed integers.
+     */
+    int: (_name) => ({ type: 'int' }),
+    /**
+     * Float property.
+     * Stored as 64-bit IEEE 754 floats.
+     */
+    float: (_name) => ({ type: 'float' }),
+    /**
+     * Boolean property.
+     */
+    bool: (_name) => ({ type: 'bool' }),
+    /**
+     * Vector property for embeddings.
+     * Stored as Float32 arrays.
+     *
+     * @param _name - Property name
+     * @param _dimensions - Vector dimensions (for documentation/validation)
+     */
+    vector: (_name, _dimensions) => ({ type: 'vector' }),
+    /**
+     * Any property (schema-less).
+     * Accepts any value type.
+     */
+    any: (_name) => ({ type: 'any' }),
+};
+/**
+ * Mark a property as optional.
+ *
+ * @example
+ * ```typescript
+ * const age = optional(prop.int('age'))
+ * ```
+ */
+function optional(spec) {
+    return { ...spec, optional: true };
+}
+/**
+ * Set a default value for a property.
+ *
+ * @example
+ * ```typescript
+ * const status = withDefault(prop.string('status'), 'active')
+ * ```
+ */
+function withDefault(spec, value) {
+    return { ...spec, default: value };
+}
+/**
+ * Define a node type with properties.
+ *
+ * Creates a node definition that can be used for all node operations
+ * (insert, update, delete, query).
+ *
+ * @param name - The node type name (must be unique)
+ * @param config - Node configuration with key function and properties
+ * @returns A NodeSpec that can be passed to ray()
+ *
+ * @example
+ * ```typescript
+ * const User = node('user', {
+ *   key: (id: string) => `user:${id}`,
+ *   props: {
+ *     name: prop.string('name'),
+ *     email: prop.string('email'),
+ *     age: optional(prop.int('age')),
+ *   },
+ * })
+ *
+ * // With template key
+ * const OrgUser = node('org_user', {
+ *   key: { kind: 'template', template: 'org:{org}:user:{id}' },
+ *   props: {
+ *     name: prop.string('name'),
+ *   },
+ * })
+ * ```
+ */
+function node(name, config) {
+    if (!config) {
+        return { name };
+    }
+    let keySpec;
+    if (typeof config.key === 'function') {
+        // Extract prefix from key function by calling it with a test value
+        const testKey = config.key('__test__');
+        const testIdx = testKey.indexOf('__test__');
+        if (testIdx !== -1) {
+            const prefix = testKey.slice(0, testIdx);
+            keySpec = { kind: 'prefix', prefix };
+        }
+        else {
+            // Couldn't extract prefix, use default
+            keySpec = { kind: 'prefix', prefix: `${name}:` };
+        }
+    }
+    else if (config.key) {
+        keySpec = config.key;
+    }
+    return {
+        name,
+        key: keySpec,
+        props: config.props,
+    };
+}
+/**
+ * Define an edge type with optional properties.
+ *
+ * Creates an edge definition that can be used for all edge operations
+ * (link, unlink, query). Edges are directional and can have properties.
+ *
+ * @param name - The edge type name (must be unique)
+ * @param props - Optional property definitions
+ * @returns An EdgeSpec that can be passed to ray()
+ *
+ * @example
+ * ```typescript
+ * // Edge with properties
+ * const knows = edge('knows', {
+ *   since: prop.int('since'),
+ *   weight: optional(prop.float('weight')),
+ * })
+ *
+ * // Edge without properties
+ * const follows = edge('follows')
+ * ```
+ */
+function edge(name, props) {
+    return { name, props };
+}
+// =============================================================================
+// Aliases for backwards compatibility
+// =============================================================================
+/** @deprecated Use `node()` instead */
+exports.defineNode = node;
+/** @deprecated Use `edge()` instead */
+exports.defineEdge = edge;
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

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