@basictech/schema 0.7.0-beta.0 → 0.11.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Basic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,8 @@
 # Basic Schema Library
 
-A TypeScript library for validating and managing Basic schemas and their data.
+A TypeScript library for validating Basic schemas and inferring SDK record types. The package root
+contains runtime validation; the dependency-light `@basictech/schema/define` subpath contains the
+typed helpers and is the preferred app-schema import.
 
 ## Installation
 
@@ -14,6 +16,24 @@ npm install @basictech/schema
 import { validateSchema, validateData, generateEmptySchema, validateUpdateSchema } from '@basictech/schema'
 ```
 
+For a typed 0.11 client schema:
+
+```typescript
+import { defineSchema, type InferRecord } from '@basictech/schema/define'
+
+export const schema = defineSchema({
+  project_id: 'my-project',
+  version: 1,
+  tables: {
+    todos: { fields: { title: { type: 'string', required: true } } },
+  },
+})
+
+type Todo = InferRecord<typeof schema, 'todos'>
+```
+
+`@basictech/core` re-exports these helpers and adds `InferValue` (the value without `id`).
+
 ## API Reference
 
 ### `validateSchema(schema: any)`
@@ -171,4 +191,4 @@ if (dataValidation.valid) {
 
 ## License
 
-MIT
+MIT

package/dist/define.d.mts

@@ -0,0 +1,43 @@
+type BasicFieldType = 'string' | 'boolean' | 'number' | 'json';
+interface BasicFieldDef {
+    type: BasicFieldType;
+    indexed?: boolean;
+    required?: boolean;
+}
+interface BasicTableDef {
+    name?: string;
+    type?: 'collection';
+    origin?: {
+        type: 'reference';
+        project_id: string;
+        table: string;
+        version?: number;
+    };
+    fields: Record<string, BasicFieldDef>;
+}
+interface BasicSchema {
+    project_id: string;
+    namespace?: string;
+    version: number;
+    tables: Record<string, BasicTableDef>;
+}
+/** Preserve schema literals for table and record type inference. */
+declare function defineSchema<const S extends BasicSchema>(schema: S): S;
+type FieldValue<F extends BasicFieldDef> = F['type'] extends 'string' ? string : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'json' ? unknown : never;
+type RequiredFieldNames<T extends BasicTableDef> = {
+    [K in keyof T['fields']]: T['fields'][K] extends {
+        required: true;
+    } ? K : never;
+}[keyof T['fields']];
+type OptionalFieldNames<T extends BasicTableDef> = Exclude<keyof T['fields'], RequiredFieldNames<T>>;
+/** The record shape for a schema table, including its Basic record id. */
+type InferRecord<S extends BasicSchema, T extends keyof S['tables']> = {
+    id: string;
+} & {
+    [K in RequiredFieldNames<S['tables'][T]>]: FieldValue<S['tables'][T]['fields'][K]>;
+} & {
+    [K in OptionalFieldNames<S['tables'][T]>]?: FieldValue<S['tables'][T]['fields'][K]>;
+};
+type TableNames<S extends BasicSchema> = keyof S['tables'] & string;
+
+export { type BasicFieldDef, type BasicFieldType, type BasicSchema, type BasicTableDef, type InferRecord, type TableNames, defineSchema };

package/dist/define.d.ts

@@ -0,0 +1,43 @@
+type BasicFieldType = 'string' | 'boolean' | 'number' | 'json';
+interface BasicFieldDef {
+    type: BasicFieldType;
+    indexed?: boolean;
+    required?: boolean;
+}
+interface BasicTableDef {
+    name?: string;
+    type?: 'collection';
+    origin?: {
+        type: 'reference';
+        project_id: string;
+        table: string;
+        version?: number;
+    };
+    fields: Record<string, BasicFieldDef>;
+}
+interface BasicSchema {
+    project_id: string;
+    namespace?: string;
+    version: number;
+    tables: Record<string, BasicTableDef>;
+}
+/** Preserve schema literals for table and record type inference. */
+declare function defineSchema<const S extends BasicSchema>(schema: S): S;
+type FieldValue<F extends BasicFieldDef> = F['type'] extends 'string' ? string : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'json' ? unknown : never;
+type RequiredFieldNames<T extends BasicTableDef> = {
+    [K in keyof T['fields']]: T['fields'][K] extends {
+        required: true;
+    } ? K : never;
+}[keyof T['fields']];
+type OptionalFieldNames<T extends BasicTableDef> = Exclude<keyof T['fields'], RequiredFieldNames<T>>;
+/** The record shape for a schema table, including its Basic record id. */
+type InferRecord<S extends BasicSchema, T extends keyof S['tables']> = {
+    id: string;
+} & {
+    [K in RequiredFieldNames<S['tables'][T]>]: FieldValue<S['tables'][T]['fields'][K]>;
+} & {
+    [K in OptionalFieldNames<S['tables'][T]>]?: FieldValue<S['tables'][T]['fields'][K]>;
+};
+type TableNames<S extends BasicSchema> = keyof S['tables'] & string;
+
+export { type BasicFieldDef, type BasicFieldType, type BasicSchema, type BasicTableDef, type InferRecord, type TableNames, defineSchema };

package/dist/define.js

@@ -0,0 +1,33 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// define.ts
+var define_exports = {};
+__export(define_exports, {
+  defineSchema: () => defineSchema
+});
+module.exports = __toCommonJS(define_exports);
+function defineSchema(schema) {
+  return schema;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineSchema
+});
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../define.ts"],"sourcesContent":["export type BasicFieldType = 'string' | 'boolean' | 'number' | 'json'\n\nexport interface BasicFieldDef {\n  type: BasicFieldType\n  indexed?: boolean\n  required?: boolean\n}\n\nexport interface BasicTableDef {\n  name?: string\n  type?: 'collection'\n  origin?: {\n    type: 'reference'\n    project_id: string\n    table: string\n    version?: number\n  }\n  fields: Record<string, BasicFieldDef>\n}\n\nexport interface BasicSchema {\n  project_id: string\n  namespace?: string\n  version: number\n  tables: Record<string, BasicTableDef>\n}\n\n/** Preserve schema literals for table and record type inference. */\nexport function defineSchema<const S extends BasicSchema>(schema: S): S {\n  return schema\n}\n\ntype FieldValue<F extends BasicFieldDef> =\n  F['type'] extends 'string' ? string\n    : F['type'] extends 'number' ? number\n      : F['type'] extends 'boolean' ? boolean\n        : F['type'] extends 'json' ? unknown\n          : never\n\ntype RequiredFieldNames<T extends BasicTableDef> = {\n  [K in keyof T['fields']]: T['fields'][K] extends { required: true } ? K : never\n}[keyof T['fields']]\n\ntype OptionalFieldNames<T extends BasicTableDef> = Exclude<keyof T['fields'], RequiredFieldNames<T>>\n\n/** The record shape for a schema table, including its Basic record id. */\nexport type InferRecord<S extends BasicSchema, T extends keyof S['tables']> =\n  { id: string }\n  & { [K in RequiredFieldNames<S['tables'][T]>]: FieldValue<S['tables'][T]['fields'][K]> }\n  & { [K in OptionalFieldNames<S['tables'][T]>]?: FieldValue<S['tables'][T]['fields'][K]> }\n\nexport type TableNames<S extends BasicSchema> = keyof S['tables'] & string\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA4BO,SAAS,aAA0C,QAAc;AACtE,SAAO;AACT;","names":[]}

package/dist/define.mjs

@@ -0,0 +1,8 @@
+// define.ts
+function defineSchema(schema) {
+  return schema;
+}
+export {
+  defineSchema
+};
+//# sourceMappingURL=define.mjs.map

package/dist/define.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../define.ts"],"sourcesContent":["export type BasicFieldType = 'string' | 'boolean' | 'number' | 'json'\n\nexport interface BasicFieldDef {\n  type: BasicFieldType\n  indexed?: boolean\n  required?: boolean\n}\n\nexport interface BasicTableDef {\n  name?: string\n  type?: 'collection'\n  origin?: {\n    type: 'reference'\n    project_id: string\n    table: string\n    version?: number\n  }\n  fields: Record<string, BasicFieldDef>\n}\n\nexport interface BasicSchema {\n  project_id: string\n  namespace?: string\n  version: number\n  tables: Record<string, BasicTableDef>\n}\n\n/** Preserve schema literals for table and record type inference. */\nexport function defineSchema<const S extends BasicSchema>(schema: S): S {\n  return schema\n}\n\ntype FieldValue<F extends BasicFieldDef> =\n  F['type'] extends 'string' ? string\n    : F['type'] extends 'number' ? number\n      : F['type'] extends 'boolean' ? boolean\n        : F['type'] extends 'json' ? unknown\n          : never\n\ntype RequiredFieldNames<T extends BasicTableDef> = {\n  [K in keyof T['fields']]: T['fields'][K] extends { required: true } ? K : never\n}[keyof T['fields']]\n\ntype OptionalFieldNames<T extends BasicTableDef> = Exclude<keyof T['fields'], RequiredFieldNames<T>>\n\n/** The record shape for a schema table, including its Basic record id. */\nexport type InferRecord<S extends BasicSchema, T extends keyof S['tables']> =\n  { id: string }\n  & { [K in RequiredFieldNames<S['tables'][T]>]: FieldValue<S['tables'][T]['fields'][K]> }\n  & { [K in OptionalFieldNames<S['tables'][T]>]?: FieldValue<S['tables'][T]['fields'][K]> }\n\nexport type TableNames<S extends BasicSchema> = keyof S['tables'] & string\n"],"mappings":";AA4BO,SAAS,aAA0C,QAAc;AACtE,SAAO;AACT;","names":[]}

package/dist/index.d.mts

@@ -21,6 +21,62 @@ type Schema = {
     version: number;
     tables: any;
 };
+type BasicFieldType = 'string' | 'boolean' | 'number' | 'json';
+interface BasicFieldDef {
+    type: BasicFieldType;
+    indexed?: boolean;
+    required?: boolean;
+}
+interface BasicTableDef {
+    name?: string;
+    type?: 'collection';
+    origin?: {
+        type: 'reference';
+        project_id: string;
+        table: string;
+        version?: number;
+    };
+    fields: Record<string, BasicFieldDef>;
+}
+/** A full Basic schema document (`{ project_id, version, tables }`). */
+interface BasicSchema {
+    project_id: string;
+    namespace?: string;
+    version: number;
+    tables: Record<string, BasicTableDef>;
+}
+/**
+ * Identity helper that preserves literal types so `InferRecord` can derive
+ * per-table record types:
+ *
+ * ```ts
+ * export const schema = defineSchema({
+ *   project_id: '…',
+ *   version: 1,
+ *   tables: { todos: { fields: { title: { type: 'string', required: true } } } },
+ * })
+ * type Todo = InferRecord<typeof schema, 'todos'>
+ * // { id: string; title: string }
+ * ```
+ */
+declare function defineSchema<const S extends BasicSchema>(schema: S): S;
+type FieldTsType<F extends BasicFieldDef> = F['type'] extends 'string' ? string : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'json' ? unknown : never;
+type RequiredFieldKeys<T extends BasicTableDef> = {
+    [K in keyof T['fields']]: T['fields'][K] extends {
+        required: true;
+    } ? K : never;
+}[keyof T['fields']];
+type OptionalFieldKeys<T extends BasicTableDef> = Exclude<keyof T['fields'], RequiredFieldKeys<T>>;
+/** The TypeScript record type for one table of a schema (plus its `id`). */
+type InferRecord<S extends BasicSchema, T extends keyof S['tables']> = {
+    id: string;
+} & {
+    [K in RequiredFieldKeys<S['tables'][T]>]: FieldTsType<S['tables'][T]['fields'][K]>;
+} & {
+    [K in OptionalFieldKeys<S['tables'][T]>]?: FieldTsType<S['tables'][T]['fields'][K]>;
+};
+/** Table names of a schema. */
+type TableNames<S extends BasicSchema> = keyof S['tables'] & string;
 /**
  * Compare two schemas and detect any differences between them
  * @param oldSchema - The original schema to compare against
@@ -220,4 +276,4 @@ declare function getJsonSchema(): {
     required: string[];
 };
 
-export { compareSchemas, generateEmptySchema, getJsonSchema, validateData, validateSchema, validateUpdateSchema };
+export { type BasicFieldDef, type BasicFieldType, type BasicSchema, type BasicTableDef, type InferRecord, type TableNames, compareSchemas, defineSchema, generateEmptySchema, getJsonSchema, validateData, validateSchema, validateUpdateSchema };

package/dist/index.d.ts

@@ -21,6 +21,62 @@ type Schema = {
     version: number;
     tables: any;
 };
+type BasicFieldType = 'string' | 'boolean' | 'number' | 'json';
+interface BasicFieldDef {
+    type: BasicFieldType;
+    indexed?: boolean;
+    required?: boolean;
+}
+interface BasicTableDef {
+    name?: string;
+    type?: 'collection';
+    origin?: {
+        type: 'reference';
+        project_id: string;
+        table: string;
+        version?: number;
+    };
+    fields: Record<string, BasicFieldDef>;
+}
+/** A full Basic schema document (`{ project_id, version, tables }`). */
+interface BasicSchema {
+    project_id: string;
+    namespace?: string;
+    version: number;
+    tables: Record<string, BasicTableDef>;
+}
+/**
+ * Identity helper that preserves literal types so `InferRecord` can derive
+ * per-table record types:
+ *
+ * ```ts
+ * export const schema = defineSchema({
+ *   project_id: '…',
+ *   version: 1,
+ *   tables: { todos: { fields: { title: { type: 'string', required: true } } } },
+ * })
+ * type Todo = InferRecord<typeof schema, 'todos'>
+ * // { id: string; title: string }
+ * ```
+ */
+declare function defineSchema<const S extends BasicSchema>(schema: S): S;
+type FieldTsType<F extends BasicFieldDef> = F['type'] extends 'string' ? string : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'json' ? unknown : never;
+type RequiredFieldKeys<T extends BasicTableDef> = {
+    [K in keyof T['fields']]: T['fields'][K] extends {
+        required: true;
+    } ? K : never;
+}[keyof T['fields']];
+type OptionalFieldKeys<T extends BasicTableDef> = Exclude<keyof T['fields'], RequiredFieldKeys<T>>;
+/** The TypeScript record type for one table of a schema (plus its `id`). */
+type InferRecord<S extends BasicSchema, T extends keyof S['tables']> = {
+    id: string;
+} & {
+    [K in RequiredFieldKeys<S['tables'][T]>]: FieldTsType<S['tables'][T]['fields'][K]>;
+} & {
+    [K in OptionalFieldKeys<S['tables'][T]>]?: FieldTsType<S['tables'][T]['fields'][K]>;
+};
+/** Table names of a schema. */
+type TableNames<S extends BasicSchema> = keyof S['tables'] & string;
 /**
  * Compare two schemas and detect any differences between them
  * @param oldSchema - The original schema to compare against
@@ -220,4 +276,4 @@ declare function getJsonSchema(): {
     required: string[];
 };
 
-export { compareSchemas, generateEmptySchema, getJsonSchema, validateData, validateSchema, validateUpdateSchema };
+export { type BasicFieldDef, type BasicFieldType, type BasicSchema, type BasicTableDef, type InferRecord, type TableNames, compareSchemas, defineSchema, generateEmptySchema, getJsonSchema, validateData, validateSchema, validateUpdateSchema };

package/dist/index.js

@@ -18,16 +18,17 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // index.ts
-var schema_exports = {};
-__export(schema_exports, {
+var index_exports = {};
+__export(index_exports, {
   compareSchemas: () => compareSchemas,
+  defineSchema: () => defineSchema,
   generateEmptySchema: () => generateEmptySchema,
   getJsonSchema: () => getJsonSchema,
   validateData: () => validateData,
   validateSchema: () => validateSchema,
   validateUpdateSchema: () => validateUpdateSchema
 });
-module.exports = __toCommonJS(schema_exports);
+module.exports = __toCommonJS(index_exports);
 
 // generated-validator.js
 var validate = validate10;
@@ -749,6 +750,9 @@ function generateEmptySchema(project_id = "", version = 0) {
     }
   };
 }
+function defineSchema(schema) {
+  return schema;
+}
 function compareSchemas(oldSchema, newSchema) {
   const changes = _getSchemaChanges(oldSchema, newSchema);
   const valid = changes.length === 0 ? true : false;
@@ -765,8 +769,7 @@ function validateSchema(schema) {
 }
 function validateCaseInsensitiveNames(schema) {
   const errors = [];
-  if (!schema.tables)
-    return errors;
+  if (!schema.tables) return errors;
   const tableNames = /* @__PURE__ */ new Set();
   for (const tableName in schema.tables) {
     const lowerTableName = tableName.toLowerCase();
@@ -784,8 +787,7 @@ function validateCaseInsensitiveNames(schema) {
   }
   for (const tableName in schema.tables) {
     const table = schema.tables[tableName];
-    if (!table.fields)
-      continue;
+    if (!table.fields) continue;
     const fieldNames = /* @__PURE__ */ new Set();
     for (const fieldName in table.fields) {
       const lowerFieldName = fieldName.toLowerCase();
@@ -927,16 +929,13 @@ function _getSchemaChanges(oldSchema, newSchema) {
   for (const tableName in newSchema.tables) {
     const newTable = newSchema.tables[tableName];
     const oldTable = oldSchema.tables[tableName];
-    if (!oldTable || !newTable.fields || !oldTable.fields)
-      continue;
+    if (!oldTable || !newTable.fields || !oldTable.fields) continue;
     for (const fieldName in newTable.fields) {
       const newField = newTable.fields[fieldName];
       const oldField = oldTable.fields[fieldName];
-      if (!oldField)
-        continue;
+      if (!oldField) continue;
       for (const prop in newField) {
-        if (prop === "type")
-          continue;
+        if (prop === "type") continue;
         if (!(prop in oldField)) {
           changes.push({
             type: "field_property_added",
@@ -957,8 +956,7 @@ function _getSchemaChanges(oldSchema, newSchema) {
         }
       }
       for (const prop in oldField) {
-        if (prop === "type")
-          continue;
+        if (prop === "type") continue;
         if (!(prop in newField)) {
           changes.push({
             type: "field_property_removed",
@@ -1025,6 +1023,7 @@ function getJsonSchema() {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   compareSchemas,
+  defineSchema,
   generateEmptySchema,
   getJsonSchema,
   validateData,