Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,15 +26,22 @@ jobs:
with:
node-version: '24.x'

- name: Path contract pre-check
run: deno task test:paths
env:
FC_SEED: 42

- name: Run Deno tests
run: deno task test --runtime=deno
env:
CI: true
FC_SEED: 42

- name: Run Node.js tests
run: deno task test --runtime=node
env:
CI: true
FC_SEED: 42

docs-build:
name: Docs Build
Expand Down Expand Up @@ -111,3 +118,4 @@ jobs:
run: deno task test --runtime=browser
env:
CI: true
FC_SEED: 42
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

### Breaking Changes

- **Store path must be absolute and non-root.** `DBInstanceConfig.path` now
throws `DBInstanceConfig.path must be an absolute, non-root path` for
relative paths, the empty string, and filesystem roots such as `/`. Resolve
the path at the call site: `new GoatDB({ path: `${Deno.cwd()}/data` })`
instead of `{ path: './data' }`. Paths are normalized on ingress, and the
check keeps `logout()` from recursively removing the process working
directory.
- Unified `Date` wire format and commit checksum (0.7.0). Typed fields now
encode as `{ "__t": "D", "__v": <epoch-seconds> }`, not a bare number.
Dates carry their tag in every checksum position. The typed-field checksum
Expand Down
3 changes: 2 additions & 1 deletion base/build-info.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { isDeno, isNode } from './common.ts';
import { cli } from './development.ts';
import { readTextFile } from './json-log/file-impl.ts';
import { parsePath } from './path.ts';
import { isWindows, normalizeNodePlatform } from './os.ts';
import type { JSONObject } from './interfaces.ts';

Expand Down Expand Up @@ -132,7 +133,7 @@ export async function generateBuildInfo(
// App version
let config: Record<string, unknown> = {};
try {
config = JSON.parse((await readTextFile(configPath)) || '{}');
config = JSON.parse((await readTextFile(parsePath(configPath))) || '{}');
} catch {
// Malformed config file — proceed without version/name
}
Expand Down
3 changes: 2 additions & 1 deletion base/file-watcher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
*/
import { isDeno, isNode } from './common.ts';
import { notReached } from './error.ts';
import * as path from './path.ts';

/**
* Represents a file system change event.
Expand Down Expand Up @@ -47,7 +48,7 @@ export function shouldRebuildAfterPathChange(
return false;
}
// Ignore paths where any of the components start with '.' or are in ignored list
const components = p.split(/[/\\]/);
const components = path.parsePath(p).split('/');
for (const comp of components) {
if (comp.startsWith('.') || ignored.includes(comp)) {
return false;
Expand Down
6 changes: 3 additions & 3 deletions base/json-log/file-impl-deno.ts
Original file line number Diff line number Diff line change
Expand Up @@ -77,11 +77,11 @@ export const FileImplDeno: FileImpl<Deno.FsFile> = {
},

getCWD() {
return Deno.cwd();
return path.parsePath(Deno.cwd());
},

getTempDir() {
return Deno.makeTempDir();
async getTempDir() {
return path.parsePath(await Deno.makeTempDir());
},

// Throw on failure like the Node and OPFS impls. Swallowing the error made
Expand Down
23 changes: 15 additions & 8 deletions base/json-log/file-impl-interface.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
* - 'start': Seek relative to the beginning of the file
* - 'end': Seek relative to the end of the file
*/
import type { PosixPath } from '../path.ts';

export type SeekFrom = 'current' | 'start' | 'end';

/**
Expand All @@ -29,6 +31,11 @@ export interface DirEntry {
* minimal set of operations required by GoatDB's persistence layer, focusing on
* the core file operations needed for the database.
*
* Path arguments and returned working/temp directories are {@link PosixPath}
* values: normalize native paths (backslashes, drive casing) once at the
* boundary with `parsePath`, then keep them POSIX internally. Use
* `equals`/`isWithin` for comparisons, never string search.
*
* The generic type parameter T represents the platform-specific file handle type.
*/
export interface FileImpl<T> {
Expand All @@ -42,7 +49,7 @@ export interface FileImpl<T> {
* the size-driven read loop would return empty bytes. A write open
* surfaces the platform error unchanged (Windows may reject earlier).
*/
open(path: string, write: boolean): Promise<T>;
open(path: PosixPath, write: boolean): Promise<T>;

/**
* Moves the file cursor to a new position.
Expand Down Expand Up @@ -97,19 +104,19 @@ export interface FileImpl<T> {
* @param path The path to the file
* @returns A promise that resolves to true if the file was removed, false otherwise
*/
remove(path: string): Promise<boolean>;
remove(path: PosixPath): Promise<boolean>;

/**
* Gets the current working directory.
* @returns The current working directory path
*/
getCWD(): string;
getCWD(): PosixPath;

/**
* Gets the path to a temporary directory.
* @returns The path to a temporary directory
*/
getTempDir(): Promise<string>;
getTempDir(): Promise<PosixPath>;

/**
* Creates a directory at the specified path.
Expand All @@ -122,15 +129,15 @@ export interface FileImpl<T> {
* @returns Resolves on success and rejects on failure. All impls (Deno,
* Node, OPFS) behave the same.
*/
mkdir(path: string): Promise<void>;
mkdir(path: PosixPath): Promise<void>;

/**
* Checks if a file or directory exists at the specified path.
*
* @param path The path to check
* @returns A promise that resolves to true if the path exists, false otherwise
*/
exists(path: string): Promise<boolean>;
exists(path: PosixPath): Promise<boolean>;

/**
* Copies a file from source to destination path.
Expand All @@ -142,7 +149,7 @@ export interface FileImpl<T> {
* @throws In browser environments, files larger than 50MB cannot be copied
* due to memory constraints.
*/
copyFile(srcPath: string, destPath: string): Promise<void>;
copyFile(srcPath: PosixPath, destPath: PosixPath): Promise<void>;

/**
* Reads the contents of a directory.
Expand All @@ -151,5 +158,5 @@ export interface FileImpl<T> {
* @returns A promise that resolves to an array of directory entries
* @throws Will throw an error if the directory doesn't exist or cannot be read
*/
readDir(path: string): Promise<DirEntry[]>;
readDir(path: PosixPath): Promise<DirEntry[]>;
}
2 changes: 1 addition & 1 deletion base/json-log/file-impl-node.ts
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ export const FileImplNode: FileImpl<NodeFsFile> = {
},

getCWD() {
return process.cwd();
return path.parsePath(process.cwd());
},

getTempDir() {
Expand Down
6 changes: 3 additions & 3 deletions base/json-log/file-impl-opfs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -206,11 +206,11 @@ export const FileImplOPFS: FileImpl<OPFSFile> = {
},

getCWD() {
return '/';
return path.parsePath('/');
},

getTempDir() {
return Promise.resolve('/temp');
return Promise.resolve(path.parsePath('/temp'));
},

async mkdir(path: string) {
Expand All @@ -236,7 +236,7 @@ export const FileImplOPFS: FileImpl<OPFSFile> = {
}
},

async copyFile(srcPath: string, destPath: string): Promise<void> {
async copyFile(srcPath, destPath): Promise<void> {
const MAX_COPY_SIZE = 50 * 1024 * 1024; // 50MB
const srcHandle = await FileImplOPFS.open(srcPath, false);
try {
Expand Down
33 changes: 19 additions & 14 deletions base/json-log/file-impl.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ export async function FileImplGet(): Promise<FileImpl<unknown>> {
* @returns Promise<Uint8Array> The contents of the file as a byte array
* @throws Will throw an error if the file cannot be opened or read
*/
export async function readFile(path: string): Promise<Uint8Array> {
export async function readFile(path: path.PosixPath): Promise<Uint8Array> {
const impl = await FileImplGet();
const handle = await impl.open(path, false);
try {
Expand Down Expand Up @@ -89,7 +89,9 @@ export async function readFile(path: string): Promise<Uint8Array> {
* @returns Promise<string | undefined> The contents of the file as a string, or
* undefined if the file could not be read
*/
export async function readTextFile(path: string): Promise<string | undefined> {
export async function readTextFile(
path: path.PosixPath,
): Promise<string | undefined> {
try {
const decoder = new TextDecoder();
return decoder.decode(await readFile(path));
Expand All @@ -108,7 +110,10 @@ export async function readTextFile(path: string): Promise<string | undefined> {
* @returns Promise<void> Resolves when the write is complete
* @throws Will throw an error if the file cannot be opened or written
*/
export async function writeFile(path: string, buf: Uint8Array): Promise<void> {
export async function writeFile(
path: path.PosixPath,
buf: Uint8Array,
): Promise<void> {
const impl = await FileImplGet();
const handle = await impl.open(path, true);
try {
Expand All @@ -131,7 +136,7 @@ export async function writeFile(path: string, buf: Uint8Array): Promise<void> {
* @returns Promise<boolean> True if the write succeeded, false if it failed
*/
export async function writeTextFile(
path: string,
path: path.PosixPath,
text: string,
): Promise<boolean> {
try {
Expand All @@ -149,7 +154,7 @@ export async function writeTextFile(
* @param path The path to check
* @returns Promise<boolean> True if the path exists, false otherwise
*/
export async function pathExists(path: string): Promise<boolean> {
export async function pathExists(path: path.PosixPath): Promise<boolean> {
const impl = await FileImplGet();
return impl.exists(path);
}
Expand All @@ -163,8 +168,8 @@ export async function pathExists(path: string): Promise<boolean> {
* @throws Will throw an error if the source file doesn't exist or copy fails
*/
export async function copyFile(
srcPath: string,
destPath: string,
srcPath: path.PosixPath,
destPath: path.PosixPath,
): Promise<void> {
const impl = await FileImplGet();
await impl.copyFile(srcPath, destPath);
Expand All @@ -177,7 +182,7 @@ export async function copyFile(
* @param path The path where to create the directory
* @returns Rejects on failure.
*/
export async function mkdir(path: string): Promise<void> {
export async function mkdir(path: path.PosixPath): Promise<void> {
const impl = await FileImplGet();
await impl.mkdir(path);
}
Expand All @@ -187,7 +192,7 @@ export async function mkdir(path: string): Promise<void> {
*
* @returns The current working directory path
*/
export async function getCWD(): Promise<string> {
export async function getCWD(): Promise<path.PosixPath> {
const impl = await FileImplGet();
return impl.getCWD();
}
Expand All @@ -198,7 +203,7 @@ export async function getCWD(): Promise<string> {
* @param dirPath The path to the directory
* @returns Promise<DirEntry[]> Array of directory entries
*/
export async function readDir(dirPath: string): Promise<DirEntry[]> {
export async function readDir(dirPath: path.PosixPath): Promise<DirEntry[]> {
const impl = await FileImplGet();
return impl.readDir(dirPath);
}
Expand All @@ -221,9 +226,9 @@ export interface WalkOptions {
* @yields Absolute file paths
*/
export async function* walkDir(
dir: string,
dir: path.PosixPath,
options?: WalkOptions,
): AsyncGenerator<string> {
): AsyncGenerator<path.PosixPath> {
const impl = await FileImplGet();
yield* walkDirImpl(
impl,
Expand All @@ -236,11 +241,11 @@ export async function* walkDir(

async function* walkDirImpl(
impl: FileImpl<unknown>,
dir: string,
dir: path.PosixPath,
includeDirs: boolean,
maxDepth: number | undefined,
currentDepth: number,
): AsyncGenerator<string> {
): AsyncGenerator<path.PosixPath> {
const entries = await impl.readDir(dir);
for (const entry of entries) {
const fullPath = path.join(dir, entry.name);
Expand Down
21 changes: 13 additions & 8 deletions base/json-log/json-log-worker-req.ts
Original file line number Diff line number Diff line change
@@ -1,19 +1,24 @@
import type { DirEntry } from './file-impl-interface.ts';
import type { PosixPath } from '../path.ts';

/** Strict file operations run in the worker, where OPFS sync handles exist. */
export type WorkerReadFileReq = {
type: 'readFile';
id: number;
path: string;
path: PosixPath;
};
export type WorkerWriteFileReq = {
type: 'writeFile';
id: number;
path: string;
path: PosixPath;
bytes: Uint8Array;
};
export type WorkerMkdirReq = { type: 'mkdir'; id: number; path: string };
export type WorkerReadDirReq = { type: 'readDir'; id: number; path: string };
export type WorkerMkdirReq = { type: 'mkdir'; id: number; path: PosixPath };
export type WorkerReadDirReq = {
type: 'readDir';
id: number;
path: PosixPath;
};

export type WorkerReadFileResp = {
type: 'readFile';
Expand All @@ -37,7 +42,7 @@ export type WorkerReadDirResp = {
export type WorkerFileReqOpen = {
type: 'open';
id: number;
path: string;
path: PosixPath;
write?: boolean;
};

Expand Down Expand Up @@ -117,7 +122,7 @@ export type WorkerFileReqAppend = {
export type WorkerReadTextFileReq = {
type: 'readTextFile';
id: number;
path: string;
path: PosixPath;
};

/**
Expand All @@ -130,7 +135,7 @@ export type WorkerReadTextFileReq = {
export type WorkerWriteTextFileReq = {
type: 'writeTextFile';
id: number;
path: string;
path: PosixPath;
text: string;
};

Expand All @@ -142,7 +147,7 @@ export type WorkerWriteTextFileReq = {
export type WorkerRemoveReq = {
type: 'remove';
id: number;
path: string;
path: PosixPath;
};

/**
Expand Down
Loading
Loading